Skip to content

Resources

Every MREG resource type is an attribute on the client, and they all expose more or less the same interface. Learn it once and it applies everywhere:

client = MregClient(..., domain="example.com")

client.host      # manage hosts
client.network   # manage networks
client.cname     # manage CNAME records


host = client.host.get("myhost")
network = client.network.get("10.0.0.0/24")

networks = client.network.list()

cname = client.cname.create(host="myhost.example.com", name="alias.example.com")

# Identifier or model object can be used for updates
client.host.update(host, description="New description")
client.network.update("10.0.0.0/24", description="New description")

# Identifier or model object can be used for deletion
client.host.delete("myhost")
client.network.delete(network)

Methods

Method Purpose
get(ident) Fetch by name, ID, or model object
get_by_name(name) Fetch by name (named resources only)
list(**query) List, optionally filtered
first(**query) Fetch the first match
count() Count resources
create(**fields) Create a resource
update(target, **fields) Update a resource
delete(target) Delete a resource
history(name) Change history (history-enabled resources)

Not every resource supports every method — read-only resources have no create/update/ delete, and only some support get_by_name or history. The per-resource Managers reference shows exactly what each manager provides.

Fetching

get interprets the argument type: a string (name), an int (ID), or an existing model object (to refresh it). If a domain is set on the client, bare names are expanded to FQDNs automatically.

host = client.host.get("myhost.example.com")
host = client.host.get("myhost")  # domain appended automatically if set
host = client.host.get(123)       # by ID
host = client.host.get(host)      # refresh a model object

By default a missing resource raises EntityNotFound. Pass required=False to return None instead:

host = client.host.get("myhost", required=False)
if host is not None:
    ...

Listing and filtering

list returns resources of that type. Keyword arguments map to model fields for filtering and are forwarded to the API. list returns up to limit results (default no limit). Fetching all hosts is very slow, and should be avoided at all costs.

all_hosts = client.host.list()
hosts = client.host.list(name__startswith="test-", limit=500)
first = client.host.first(name__startswith="test-")
n = client.host.count(name__startswith="test-")

Creating

create takes keyword arguments matching the model's fields. Every create method returns the created object on success. An HTTPStatusError subclass is raised if the server rejects the creation (e.g. ConflictError if it already exists).

host = client.host.create(
    name="newhost.example.com",
    comment="Created via the API",
    fetch_after_create=True,
)

Updating

update accepts a model object or an identifier (name, ID), plus the fields to change. The available fields vary depending on the resource. An HTTPStatusError subclass is raised if the server rejects the update.

client.host.update(
    host, # or name or ID
    comment="Updated comment",
    ttl=3600,
)

Refreshing after update

Updating a resource does not modify the client-side copy of the object. You can call refresh() to fetch the updated state of the object:

client.host.update(host, comment="Updated comment")
refreshed = client.host.refresh(host)

Deleting

delete accepts a model object or an identifier. An HTTPStatusError subclass is raised if the server rejects the deletion.

client.host.delete(host)               # by object
client.host.delete("newhost.example.com")  # by name
client.host.delete(123)                    # by ID

Network communities, a different interface

Network communities are tied to existing networks. To that end, all operations on communities require an existing network community object, meaning the MregClient.community (alt: MregClient.network.community) methods do not accept name (str) or ID (int) arguments - only Community objects.

In practice, this looks like:

# Create a community
community = client.community.create("lab1", "Lab network community", network="192.168.1.0/24")

# Fetch an existing community requires a network argument
community = client.community.get("lab1", "192.168.1.0/24")  # by name
community = client.community.get(123, "192.168.1.0/24")  # by ID

# Searching/listing also requires a network argument
community = client.community.first("192.168.1.0/24", description="Lab network community")
communities = client.community.list("192.168.1.0/24", description="Lab network community")

# Modification of existing community resources do not require a network argument
client.community.update(community, description="Updated description")
client.community.add_host(community, "host1.example.com")
client.community.remove_host(community, "host1.example.com")
client.community.delete(community)

All managers

Every attribute below is a manager on the client. Follow the link for its full method reference.

Attribute Resource Reference
MregClient.host Hosts HostManager
MregClient.hostgroup Host groups HostGroupManager
MregClient.ipaddress IP addresses IPAddressManager
MregClient.network Networks NetworkManager
MregClient.networkpolicy
MregClient.network.policy
Network policies NetworkPolicyManager
MregClient.networkpolicyattribute
MregClient.network.policy.attribute
Network policy attributes NetworkPolicyAttributeManager
MregClient.community
MregClient.network.community
Network communities CommunityManager
MregClient.cname CNAME records CNAMEManager
MregClient.mx MX records MXManager
MregClient.txt TXT records TXTManager
MregClient.naptr NAPTR records NAPTRManager
MregClient.srv SRV records SrvManager
MregClient.sshfp SSHFP records SSHFPManager
MregClient.ptroverride PTR overrides PTROverrideManager
MregClient.hinfo HINFO records HInfoManager
MregClient.location Locations LocationManager
MregClient.bacnetid BACnet IDs BacnetIDManager
MregClient.role
MregClient.policy.role
Host policy roles RoleManager
MregClient.atom
MregClient.policy.atom
Host policy atoms AtomManager
MregClient.label
MregClient.policy.label
Labels LabelManager
MregClient.zone Zones ZoneManager
MregClient.delegation Zone delegations DelegationManager
MregClient.nameserver Nameservers NameServerManager
MregClient.dhcphostipv4 IPv4 DHCP hosts DhcpHostIPv4Manager
MregClient.dhcphostipv6 IPv6 DHCP hosts DhcpHostIPv6Manager
MregClient.dhcphostipv6byipv4 IPv6-via-IPv4 DHCP hosts DhcpHostIPv6ByIPv4Manager
MregClient.permission Permissions PermissionManager
MregClient.meta Server metadata & health MetaManagerNamespace

Nested sub-managers

A few managers are also composed logically on top of each other, so as to categorize related operations.

  • client.network ⇾ client.network.policy, client.network.community
  • client.network.policy ⇾ client.network.policy.attribute
  • client.meta ⇾ client.meta.version, client.meta.libraries, client.meta.userinfo, client.meta.ldap, client.meta.heartbeat, client.meta.health
  • client.policy ⇾ client.policy.role, client.policy.atom, client.policy.label