Skip to content

Host

add_host_to_hostgroup

add_host_to_hostgroup <HOSTS> <HOSTGROUPS> [OPTIONS]

Add hosts to host groups.

Host name and group arguments are interpreted as IDs if they are numeric.

Examples

Add a host to a host group

add_host_to_hostgroup 'My host' 'My host group'

Add multiple hosts to a host group

add_host_to_hostgroup 'host1,host2' 'My host group'

Add multiple hosts to multiple host groups

add_host_to_hostgroup 'host1,host2' 'My host group,Another group'

Arguments

HOSTS
Host names or IDs. Comma-separated. Supports wildcards.
Type: text
Required: ✅

HOSTGROUPS
Host group names or IDs. Comma-separated. Supports wildcards.
Type: text
Required: ✅

Options

--dryrun
Preview changes
Type: boolean
Default: False

create_host

create_host <HOSTNAME_OR_IP> [OPTIONS]

Create a host.

Always adds the host to the default host group unless --no-default-hostgroup is specified.

Selects a random proxy by default unless --proxy - is specified.

Arguments

HOSTNAME_OR_IP
Hostname or IP
Type: text
Required: ✅

Options

--hostgroup <HOSTGROUPS>
Hostgroup name(s) or ID(s). Comma-separated.
Type: text

--proxy <PROXY>
Proxy server used to monitor the host. Supports regular expressions.
Type: text
Default: .+

--status <STATUS>
Host monitoring status.
Type: choice
Choices: on, off, 0, 1
Default: on

--default-hostgroup/--no-default-hostgroup
Add host to default host group(s) defined in config.
Type: boolean
Default: True

--name <NAME>
Visible name of the host. Uses hostname or IP if omitted.
Type: text

--description <DESCRIPTION>
Description of the host.
Type: text

create_host_interface

create_host_interface <HOSTNAME> [OPTIONS]

Create a host interface.

Creates an SNMPv2 interface by default. Use --type to specify a different type. One of --dns and --ip is required. If both are specified, --connection is required.

NOTE: Can only create secondary host interfaces for interfaces of types that already have a default interface. (API limitation)

Examples

Create an SNMPv2 interface on host 'foo.example.com' with derived DNS name 'foo.example.com' (default)

create_host_interface foo.example.com

Create an SNMPv2 interface on host 'foo.example.com' with IP connection

create_host_interface foo.example.com --type snmp --ip 127.0.0.1

Create an SNMPv2 interface on host 'foo.example.com' with different DNS name

create_host_interface foo.example.com --type snmp --dns snmp.example.com

Create an SNMPv2 interface on host 'foo' with both IP and DNS, using DNS as enabled address

create_host_interface foo --type snmp --connection dns --dns snmp.example.com --ip 127.0.0.1

Create an SNMPv3 interface on host 'foo.example.com'

create_host_interface foo.example.com --type snmp --snmp-version 3 --snmp-context-name mycontext --snmp-security-name myuser --snmp-security-level authpriv --snmp-auth-protocol MD5 --snmp-auth-passphrase mypass --snmp-priv-protocol DES --snmp-priv-passphrase myprivpass

Create an Agent interface on host 'foo.example.com'

create_host_interface foo.example.com --type agent

Arguments

HOSTNAME
Name of host to create interface on.
Type: text
Required: ✅

Options

--connection <CONNECTION>
Interface connection mode. Required if both --ip and --dns are specified.
Type: choice
Choices: DNS, IP, 0, 1

--type <TYPE_>
Interface type. SNMP enables --snmp- options.
Type: choice
Choices: Agent, SNMP, IPMI, JMX, 1, 2, 3, 4
Default:* SNMP

--port <PORT>
Interface port. Defaults to 10050 for agent, 161 for SNMP, 623 for IPMI, and 12345 for JMX.
Type: text

--ip <IP>
IP address of interface.
Type: text

--dns <DNS>
DNS address of interface.
Type: text

--default/--no-default
Whether this is the default interface.
Type: boolean
Default: True

--snmp-version <SNMP_VERSION>
SNMP version.
Type: integer range
Min: 1
Max: 3
Default: 2

--snmp-bulk/--no-snmp-bulk
Use bulk SNMP requests.
Type: boolean
Default: True

--snmp-community <SNMP_COMMUNITY>
SNMPv{1,2} community.
Type: text
Default: ${SNMP_COMMUNITY}

--snmp-max-repetitions <SNMP_MAX_REPETITIONS>
Max repetitions for SNMPv{2,3} bulk requests.
Type: integer range
Min: 1
Default: 10

--snmp-security-name <SNMP_SECURITY_NAME>
SNMPv3 security name.
Type: text

--snmp-context-name <SNMP_CONTEXT_NAME>
SNMPv3 context name.
Type: text

--snmp-security-level <SNMP_SECURITY_LEVEL>
SNMPv3 security level.
Type: choice
Choices: noAuthNoPriv, authNoPriv, authPriv, 0, 1, 2

--snmp-auth-protocol <SNMP_AUTH_PROTOCOL>
SNMPv3 auth protocol (authNoPriv & authPriv).
Type: choice
Choices: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, 0, 1, 2, 3, 4, 5

--snmp-auth-passphrase <SNMP_AUTH_PASSPHRASE>
SNMPv3 auth passphrase (authNoPriv & authPriv).
Type: text

--snmp-priv-protocol <SNMP_PRIV_PROTOCOL>
SNMPv3 priv protocol (authPriv)
Type: choice
Choices: DES, AES, AES128, AES192, AES256, AES192C, AES256C, 0, 1, 1, 2, 3, 4, 5

--snmp-priv-passphrase <SNMP_PRIV_PASSPHRASE>
SNMPv3 priv passphrase (authPriv).
Type: text

create_hostgroup

create_hostgroup <HOSTGROUP> [OPTIONS]

Create a new host group.

Assigns default user group permissions by default.

  • --rw-groups defaults to config option app.default_admin_usergroups.
  • --ro-groups defaults to config option app.default_create_user_usergroups.
  • Use --no-usergroup-permissions to create a group without any user group permissions.

Examples

Create a host group with default user group permissions

create_hostgroup 'My Host Group'

Create a host group with specific RO and RW groups

create_hostgroup 'My Host Group' --ro-groups users --rw-groups admins

Create a host group with no user group permissions

create_hostgroup 'My Host Group' --no-usergroup-permissions

Arguments

HOSTGROUP
Name of host group.
Type: text
Required: ✅

Options

--rw-groups <RW_GROUPS>
User group(s) to give read/write permissions. Comma-separated.
Type: text

--ro-groups <RO_GROUPS>
User group(s) to give read-only permissions. Comma-separated.
Type: text

--no-usergroup-permissions
Do not assign user group permissions.
Type: boolean
Default: False

extend_hostgroup

extend_hostgroup <SRC_GROUP> <DEST_GROUP> [OPTIONS]

Add all hosts from a host group to other host groups.

The source group is not modified. Existing hosts in the destination group(s) are not removed or modified.

Arguments

SRC_GROUP
Group to get hosts from.
Type: text
Required: ✅

DEST_GROUP
Group(s) to add hosts to. Comma-separated. Supports wildcards.
Type: text
Required: ✅

Options

--dryrun
Show hosts and groups without making changes.
Type: boolean
Default: False

monitor_host

monitor_host <HOSTNAME> <NEW_STATUS>

Monitor or unmonitor a host.

Arguments

HOSTNAME
Name of host
Type: text
Required: ✅

NEW_STATUS
Monitoring status
Type: choice
Choices: on, off, 0, 1
Required: ✅

move_hosts

move_hosts <SRC_GROUP> <DEST_GROUP> [OPTIONS]

Move all hosts from one host group to another.

Arguments

SRC_GROUP
Group to move hosts from.
Type: text
Required: ✅

DEST_GROUP
Group to move hosts to.
Type: text
Required: ✅

Options

--rollback/--no-rollback
Rollback changes if hosts cannot be removed from source group afterwards.
Type: boolean
Default: True

--dryrun
Show hosts and groups without making changes.
Type: boolean
Default: False

remove_host

remove_host <HOSTNAME>

Delete a host.

Arguments

HOSTNAME
Name of host to remove.
Type: text
Required: ✅

remove_host_from_hostgroup

remove_host_from_hostgroup <HOSTS> <HOSTGROUPS> [OPTIONS]

Remove hosts from host groups.

Examples

Remove a host to a host group

remove_host_from_hostgroup 'My host' 'My host group'

Remove multiple hosts from a host group

remove_host_from_hostgroup 'host1,host2' 'My host group'

Remove multiple hosts from multiple host groups

remove_host_from_hostgroup 'host1,host2' 'My host group,Another group'

Arguments

HOSTS
Host names or IDs. Comma-separated. Supports wildcards.
Type: text
Required: ✅

HOSTGROUPS
Host group names or IDs. Comma-separated. Supports wildcards.
Type: text
Required: ✅

Options

--dryrun
Preview changes
Type: boolean
Default: False

remove_host_interface

remove_host_interface <INTERFACE_ID>

Remove a host interface.

Arguments

INTERFACE_ID
ID of interface to remove.
Type: text
Required: ✅

remove_hostgroup

remove_hostgroup <HOSTGROUP> [OPTIONS]

Delete a host group.

Arguments

HOSTGROUP
Name of host group(s) to delete. Comma-separated.
Type: text
Required: ✅

Options

--force
Remove host group even if it contains hosts.
Type: boolean
Default: False

show_host

show_host <HOSTNAME_OR_ID> [OPTIONS]

Show a specific host.

Arguments

HOSTNAME_OR_ID
Hostname or ID.
Type: text
Required: ✅

Options

--active <ACTIVE>
Active interface availability.
Type: choice
Choices: unknown, available, unavailable, 0, 1, 2

--maintenance/--no-maintenance
Maintenance status.
Type: boolean

--monitored/--no-monitored
Monitoring status.
Type: boolean

show_host_interfaces

show_host_interfaces <HOSTNAME_OR_ID>

Show host interfaces.

Arguments

HOSTNAME_OR_ID
Hostname or ID
Type: text
Required: ✅

show_host_inventory

show_host_inventory <HOSTNAME_OR_ID>

Show host inventory details for a specific host.

Arguments

HOSTNAME_OR_ID
Hostname or ID
Type: text
Required: ✅

show_hostgroup

show_hostgroup <HOSTGROUP>

Show details of a host group.

Arguments

HOSTGROUP
Name of host group.
Type: text
Required: ✅

show_hostgroup_permissions

show_hostgroup_permissions <HOSTGROUPS>

Show usergroups with permissions for the given hostgroup.

Shows permissions for all host groups by default.

Arguments

HOSTGROUPS
Host group name(s). Comma-separated. Supports wildcards.
Type: text
Required: ✅

show_hostgroups

show_hostgroups <NAME> [OPTIONS]

Show details for host groups.

Limits results to 20 by default. Fetching all host groups with hosts can be extremely slow.

Examples

Show all host groups

show_hostgroups --limit 0

Show all host groups starting with 'Web-'

show_hostgroups 'Web-*'

Show host groups with 'web' in the name

show_hostgroups '*web*'

Arguments

NAME
Name of host group(s). Comma-separated. Supports wildcards.
Type: text
Required: ✅

Options

--hosts/--no-hosts
Show hosts in each host group.
Type: boolean
Default: True

--limit, -n <LIMIT>
Limit the number of results. 0 to show all.
Type: integer
Default: 0

show_hosts

show_hosts <HOSTNAME_OR_ID> [OPTIONS]

Show all hosts.

Hosts can be filtered by agent, monitoring and maintenance status. Hosts are sorted by name.

Examples

Show all monitored (enabled) hosts

show_hosts --monitored

Show all hosts with names ending in '.example.com'

show_hosts '*.example.com'

Show all hosts with names ending in '.example.com' or '.example.net'

show_hosts '*.example.com,*.example.net'

Show all hosts with names ending in '.example.com' or '.example.net'

show_hosts '*.example.com,*.example.net'

Show all hosts from a given hostgroup

show_hosts --hostgroup 'Linux servers'

Arguments

HOSTNAME_OR_ID
Hostname pattern or ID to filter by. Comma-separated. Supports wildcards.
Type: text

Options

--hostgroup <HOSTGROUP>
Hostgroup name(s) or ID(s). Comma-separated.
Type: text

--active <ACTIVE>
Active interface availability.
Type: choice
Choices: unknown, available, unavailable, 0, 1, 2

--maintenance/--no-maintenance
Maintenance status.
Type: boolean

--monitored/--unmonitored
Monitoring status.
Type: boolean

--limit, -n <LIMIT>
Limit the number of results. 0 to show all.
Type: integer
Default: 0

update_host

update_host <HOSTNAME_OR_IP> [OPTIONS]

Update basic information about a host.

Other notable commands to update a host:

  • add_host_to_hostgroup
  • create_host_interface
  • monitor_host
  • remove_host_from_hostgroup
  • update_host_interface
  • update_host_inventory

Arguments

HOSTNAME_OR_IP
Hostname or IP
Type: text
Required: ✅

Options

--name <NAME>
Visible name of the host.
Type: text

--description <DESCRIPTION>
Description of the host.
Type: text

update_host_interface

update_host_interface <INTERFACE_ID> [OPTIONS]

Update a host interface.

Host interface type cannot be changed.

Examples

Update the IP address of interface 123.

update_host_interface 123 --ip 127.0.0.1

Change connection type of interface 123 to IP.

update_host_interface 123 --connection ip

Change SNMP community of interface 234 to 'public'.

update_host_interface 234 --snmp-community public

Arguments

INTERFACE_ID
ID of interface to update.
Type: text
Required: ✅

Options

--connection <CONNECTION>
Interface connection mode.
Type: choice
Choices: DNS, IP, 0, 1

--port <PORT>
Interface port.
Type: text

--ip <IP>
IP address of interface.
Type: text

--dns <DNS>
DNS address of interface.
Type: text

--default/--no-default
Default interface.
Type: boolean
Default: True

--snmp-version <SNMP_VERSION>
SNMP version.
Type: integer range
Min: 1
Max: 3

--snmp-bulk/--no-snmp-bulk
Use bulk SNMP requests.
Type: boolean

--snmp-community <SNMP_COMMUNITY>
SNMPv{1,2} community.
Type: text

--snmp-max-repetitions <SNMP_MAX_REPETITIONS>
Max repetitions for SNMPv{2,3} bulk requests.
Type: integer range
Min: 1

--snmp-security-name <SNMP_SECURITY_NAME>
SNMPv3 security name.
Type: text

--snmp-context-name <SNMP_CONTEXT_NAME>
SNMPv3 context name.
Type: text

--snmp-security-level <SNMP_SECURITY_LEVEL>
SNMPv3 security level.
Type: choice
Choices: noAuthNoPriv, authNoPriv, authPriv, 0, 1, 2

--snmp-auth-protocol <SNMP_AUTH_PROTOCOL>
SNMPv3 auth protocol (authNoPriv & authPriv).
Type: choice
Choices: MD5, SHA1, SHA224, SHA256, SHA384, SHA512, 0, 1, 2, 3, 4, 5

--snmp-auth-passphrase <SNMP_AUTH_PASSPHRASE>
SNMPv3 auth passphrase (authNoPriv & authPriv).
Type: text

--snmp-priv-protocol <SNMP_PRIV_PROTOCOL>
SNMPv3 priv protocol (authPriv)
Type: choice
Choices: DES, AES, AES128, AES192, AES256, AES192C, AES256C, 0, 1, 1, 2, 3, 4, 5

--snmp-priv-passphrase <SNMP_PRIV_PASSPHRASE>
SNMPv3 priv passphrase (authPriv).
Type: text

update_host_inventory

update_host_inventory <HOSTNAME_OR_ID> <KEY> <VALUE>

Update a host inventory field.

Inventory fields in the API do not always match Web GUI field names. Use zabbix-cli -o json show_host_inventory <hostname> to see the available fields.

Arguments

HOSTNAME_OR_ID
Hostname or ID of host.
Type: text
Required: ✅

KEY
Inventory key
Type: text
Required: ✅

VALUE
Inventory value
Type: text
Required: ✅