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:
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.
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:
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.networkpolicyMregClient.network.policy |
Network policies | NetworkPolicyManager |
MregClient.networkpolicyattributeMregClient.network.policy.attribute |
Network policy attributes | NetworkPolicyAttributeManager |
MregClient.communityMregClient.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.roleMregClient.policy.role |
Host policy roles | RoleManager |
MregClient.atomMregClient.policy.atom |
Host policy atoms | AtomManager |
MregClient.labelMregClient.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.communityclient.network.policy⇾client.network.policy.attributeclient.meta⇾client.meta.version,client.meta.libraries,client.meta.userinfo,client.meta.ldap,client.meta.heartbeat,client.meta.healthclient.policy⇾client.policy.role,client.policy.atom,client.policy.label