Basic methods for interaction with the network device through the virtual proxy 'napalm'.
codeauthor: | Mircea Ulinic <mircea@cloudflare.com> & Jerome Fleury <jf@cloudflare.com> |
---|---|
maturity: | new |
depends: | napalm |
platform: | unix |
New in version 2016.11.0.
Changed in version 2017.7.0.
salt.modules.napalm_network.
arp
(*args, **kwargs)¶NAPALM returns a list of dictionaries with details of the ARP entries.
Parameters: |
|
---|---|
Returns: | List of the entries in the ARP table |
CLI Example:
salt '*' net.arp
salt '*' net.arp macaddr='5c:5e:ab:da:3c:f0'
Example output:
[
{
'interface' : 'MgmtEth0/RSP0/CPU0/0',
'mac' : '5c:5e:ab:da:3c:f0',
'ip' : '172.17.17.1',
'age' : 1454496274.84
},
{
'interface': 'MgmtEth0/RSP0/CPU0/0',
'mac' : '66:0e:94:96:e0:ff',
'ip' : '172.17.17.2',
'age' : 1435641582.49
}
]
salt.modules.napalm_network.
cli
(*args, **kwargs)¶Returns a dictionary with the raw output of all commands passed as arguments.
Parameters: | commands -- list of commands to be executed on the device |
---|---|
Returns: | a dictionary with the mapping between each command and its raw output |
CLI Example:
salt '*' net.cli "show version" "show chassis fan"
Example output:
{
u'show version and haiku': u'Hostname: re0.edge01.arn01
Model: mx480
Junos: 13.3R6.5
Help me, Obi-Wan
I just saw Episode Two
You're my only hope
',
u'show chassis fan' : u'Item Status RPM Measurement
Top Rear Fan OK 3840 Spinning at intermediate-speed
Bottom Rear Fan OK 3840 Spinning at intermediate-speed
Top Middle Fan OK 3900 Spinning at intermediate-speed
Bottom Middle Fan OK 3840 Spinning at intermediate-speed
Top Front Fan OK 3810 Spinning at intermediate-speed
Bottom Front Fan OK 3840 Spinning at intermediate-speed
'
}
salt.modules.napalm_network.
commit
(*args, **kwargs)¶Commits the configuration changes made on the network device.
CLI Example:
salt '*' net.commit
salt.modules.napalm_network.
compare_config
(*args, **kwargs)¶Returns the difference between the running config and the candidate config.
CLI Example:
salt '*' net.compare_config
salt.modules.napalm_network.
config
(*args, **kwargs)¶New in version 2017.7.0.
Return the whole configuration of the network device. By default, it will return all possible configuration sources supported by the network device. At most, there will be:
To return only one of the configurations, you can use the source
argument.
Which configuration type you want to display, default is all of them.
Options:
Returns: | The object returned is a dictionary with the following keys:
|
---|
CLI Example:
salt '*' net.config
salt '*' net.config source=candidate
salt.modules.napalm_network.
config_changed
(*args, **kwargs)¶Will prompt if the configuration has been changed.
Returns: | A tuple with a boolean that specifies if the config was changed on the device. And a string that provides more details of the reason why the configuration was not changed. |
---|
CLI Example:
salt '*' net.config_changed
salt.modules.napalm_network.
config_control
(*args, **kwargs)¶Will check if the configuration was changed. If differences found, will try to commit. In case commit unsuccessful, will try to rollback.
Returns: | A tuple with a boolean that specifies if the config was changed/committed/rollbacked on the device. And a string that provides more details of the reason why the configuration was not committed properly. |
---|
CLI Example:
salt '*' net.config_control
salt.modules.napalm_network.
connected
(*args, **kwargs)¶Specifies if the connection to the device succeeded.
CLI Example:
salt '*' net.connected
salt.modules.napalm_network.
discard_config
(*args, **kwargs)¶Discards the changes applied.
CLI Example:
salt '*' net.discard_config
salt.modules.napalm_network.
environment
(*args, **kwargs)¶Returns the environment of the device.
CLI Example:
salt '*' net.environment
Example output:
{
'fans': {
'Bottom Rear Fan': {
'status': True
},
'Bottom Middle Fan': {
'status': True
},
'Top Middle Fan': {
'status': True
},
'Bottom Front Fan': {
'status': True
},
'Top Front Fan': {
'status': True
},
'Top Rear Fan': {
'status': True
}
},
'memory': {
'available_ram': 16349,
'used_ram': 4934
},
'temperature': {
'FPC 0 Exhaust A': {
'is_alert': False,
'temperature': 35.0,
'is_critical': False
}
},
'cpu': {
'1': {
'%usage': 19.0
},
'0': {
'%usage': 35.0
}
}
}
salt.modules.napalm_network.
facts
(*args, **kwargs)¶Returns characteristics of the network device. :return: a dictionary with the following keys:
- uptime - Uptime of the device in seconds.
- vendor - Manufacturer of the device.
- model - Device model.
- hostname - Hostname of the device
- fqdn - Fqdn of the device
- os_version - String with the OS version running on the device.
- serial_number - Serial number of the device
- interface_list - List of the interfaces of the device
CLI Example:
salt '*' net.facts
Example output:
{
'os_version': u'13.3R6.5',
'uptime': 10117140,
'interface_list': [
'lc-0/0/0',
'pfe-0/0/0',
'pfh-0/0/0',
'xe-0/0/0',
'xe-0/0/1',
'xe-0/0/2',
'xe-0/0/3',
'gr-0/0/10',
'ip-0/0/10'
],
'vendor': u'Juniper',
'serial_number': u'JN131356FBFA',
'model': u'MX480',
'hostname': u're0.edge05.syd01',
'fqdn': u're0.edge05.syd01'
}
salt.modules.napalm_network.
interfaces
(*args, **kwargs)¶Returns details of the interfaces on the device.
Returns: | Returns a dictionary of dictionaries. The keys for the first dictionary will be the interfaces in the devices. |
---|
CLI Example:
salt '*' net.interfaces
Example output:
{
u'Management1': {
'is_up': False,
'is_enabled': False,
'description': u'',
'last_flapped': -1,
'speed': 1000,
'mac_address': u'dead:beef:dead',
},
u'Ethernet1':{
'is_up': True,
'is_enabled': True,
'description': u'foo',
'last_flapped': 1429978575.1554043,
'speed': 1000,
'mac_address': u'beef:dead:beef',
}
}
salt.modules.napalm_network.
ipaddrs
(*args, **kwargs)¶Returns IP addresses configured on the device.
Returns: | A dictionary with the IPv4 and IPv6 addresses of the interfaces. Returns all configured IP addresses on all interfaces as a dictionary of dictionaries. Keys of the main dictionary represent the name of the interface. Values of the main dictionary represent are dictionaries that may consist of two keys 'ipv4' and 'ipv6' (one, both or none) which are themselvs dictionaries with the IP addresses as keys. |
---|
CLI Example:
salt '*' net.ipaddrs
Example output:
{
u'FastEthernet8': {
u'ipv4': {
u'10.66.43.169': {
'prefix_length': 22
}
}
},
u'Loopback555': {
u'ipv4': {
u'192.168.1.1': {
'prefix_length': 24
}
},
u'ipv6': {
u'1::1': {
'prefix_length': 64
},
u'2001:DB8:1::1': {
'prefix_length': 64
},
u'FE80::3': {
'prefix_length': u'N/A'
}
}
}
}
salt.modules.napalm_network.
lldp
(*args, **kwargs)¶Returns a detailed view of the LLDP neighbors.
Parameters: | interface -- interface name to filter on |
---|---|
Returns: | A dictionary with the LLDL neighbors. The keys are the interfaces with LLDP activated on. |
CLI Example:
salt '*' net.lldp
salt '*' net.lldp interface='TenGigE0/0/0/8'
Example output:
{
'TenGigE0/0/0/8': [
{
'parent_interface': u'Bundle-Ether8',
'interface_description': u'TenGigE0/0/0/8',
'remote_chassis_id': u'8c60.4f69.e96c',
'remote_system_name': u'switch',
'remote_port': u'Eth2/2/1',
'remote_port_description': u'Ethernet2/2/1',
'remote_system_description': u'Cisco Nexus Operating System (NX-OS) Software 7.1(0)N1(1a)
TAC support: http://www.cisco.com/tac
Copyright (c) 2002-2015, Cisco Systems, Inc. All rights reserved.',
'remote_system_capab': u'B, R',
'remote_system_enable_capab': u'B'
}
]
}
salt.modules.napalm_network.
load_config
(*args, **kwargs)¶Applies configuration changes on the device. It can be loaded from a file or from inline string. If you send both a filename and a string containing the configuration, the file has higher precedence.
By default this function will commit the changes. If there are no changes, it does not commit and
the flag already_configured
will be set as True
to point this out.
To avoid committing the configuration, set the argument test
to True
and will discard (dry run).
To keep the changes but not commit, set commit
to False
.
To replace the config, set replace
to True
.
Path to the file containing the desired configuration. This can be specified using the absolute path to the file, or using one of the following URL schemes:
salt://
, to fetch the template from the Salt fileserver.http://
or https://
ftp://
s3://
swift://
Changed in version 2017.7.3.
filename
is specified.True
, will apply the config, discard and return the changes. Default: False
and will commit the changes on the device.True
.Debug mode. Will insert a new key under the output dictionary, as loaded_config
containing the raw
configuration loaded on the device.
New in version 2016.11.2.
Load and replace the configuration. Default: False
.
New in version 2016.11.2.
base
Specifies the Salt environment name.
New in version 2017.7.3.
Returns: | a dictionary having the following keys: |
---|
False
only in case of failure. In case there are no changes to be applied and successfully performs all operations it is still True
and so will be the already_configured
flag (example below)debug
to be set as True
CLI Example:
salt '*' net.load_config text='ntp peer 192.168.0.1'
salt '*' net.load_config filename='/absolute/path/to/your/file'
salt '*' net.load_config filename='/absolute/path/to/your/file' test=True
salt '*' net.load_config filename='/absolute/path/to/your/file' commit=False
Example output:
{
'comment': 'Configuration discarded.',
'already_configured': False,
'result': True,
'diff': '[edit interfaces xe-0/0/5]+ description "Adding a description";'
}
salt.modules.napalm_network.
load_template
(*args, **kwargs)¶Renders a configuration template (default: Jinja) and loads the result on the device.
By default this function will commit the changes. If there are no changes,
it does not commit, discards he config and the flag already_configured
will be set as True
to point this out.
To avoid committing the configuration, set the argument test
to True
and will discard (dry run).
To preserve the changes, set commit
to False
.
However, this is recommended to be used only in exceptional cases
when there are applied few consecutive states
and/or configuration changes.
Otherwise the user might forget that the config DB is locked
and the candidate config buffer is not cleared/merged in the running config.
To replace the config, set replace
to True
.
Warning
The support for native NAPALM templates will be dropped in Salt Fluorine.
Implicitly, the template_path
argument will be removed.
Identifies path to the template source.
The template can be either stored on the local machine, either remotely.
The recommended location is under the file_roots
as specified in the master config file.
For example, let's suppose the file_roots
is configured as:
file_roots:
base:
- /etc/salt/states
Placing the template under /etc/salt/states/templates/example.jinja
,
it can be used as salt://templates/example.jinja
.
Alternatively, for local files, the user can specify the absolute path.
If remotely, the source can be retrieved via http
, https
or ftp
.
Examples:
salt://my_template.jinja
/absolute/path/to/my_template.jinja
http://example.com/template.cheetah
https:/example.com/template.mako
ftp://example.com/template.py
Required only in case the argument template_name
provides only the file basename
when referencing a local template using the absolute path.
E.g.: if template_name
is specified as my_template.jinja
,
in order to find the template, this argument must be provided:
template_path: /absolute/path/to/
.
Note
This argument will be deprecated beginning with release codename Fluorine
.
Hash of the template file. Format: {hash_type: 'md5', 'hsum': <md5sum>}
New in version 2016.11.2.
When template_hash
refers to a remote file,
this specifies the filename to look for in that file.
New in version 2016.11.2.
Owner of file.
New in version 2016.11.2.
Group owner of file.
New in version 2016.11.2.
Permissions of file.
New in version 2016.11.2.
Specifies the template environment. This will influence the relative imports inside the templates.
New in version 2016.11.2.
The following templates engines are supported:
New in version 2016.11.2.
If True
, hash verification of remote file sources
(http://
, https://
, ftp://
) will be skipped,
and the source_hash
argument will be ignored.
New in version 2016.11.2.
True
, will apply the config,
discard and return the changes.
Default: False
and will commit the changes on the device.True
)Debug mode. Will insert a new key under the output dictionary,
as loaded_config
containing the raw result after the template was rendered.
New in version 2016.11.2.
Load and replace the configuration.
New in version 2016.11.2.
Default variables/context passed to the template.
New in version 2016.11.2.
Dictionary with the arguments/context to be used when the template is rendered.
Note
Do not explicitly specify this argument. This represents any other variable that will be sent to the template rendering system. Please see the examples below!
Returns: | a dictionary having the following keys: |
---|
False
only in case of failure. In case there are no changes to be applied and
successfully performs all operations it is still True
and so will be
the already_configured
flag (example below)debug
to be set as True
The template can use variables from the grains
, pillar
or opts
, for example:
{% set router_model = grains.get('model') -%}
{% set router_vendor = grains.get('vendor') -%}
{% set os_version = grains.get('version') -%}
{% set hostname = pillar.get('proxy', {}).get('host') -%}
{% if router_vendor|lower == 'juniper' %}
system {
host-name {{hostname}};
}
{% elif router_vendor|lower == 'cisco' %}
hostname {{hostname}}
{% endif %}
CLI Examples:
salt '*' net.load_template set_ntp_peers peers=[192.168.0.1] # uses NAPALM default templates
# inline template:
salt -G 'os:junos' net.load_template set_hostname template_source='system { host-name {{host_name}}; }' host_name='MX480.lab'
# inline template using grains info:
salt -G 'os:junos' net.load_template set_hostname template_source='system { host-name {{grains.model}}.lab; }'
# if the device is a MX480, the command above will set the hostname as: MX480.lab
# inline template using pillar data:
salt -G 'os:junos' net.load_template set_hostname template_source='system { host-name {{pillar.proxy.host}}; }'
salt '*' net.load_template my_template template_path='/tmp/tpl/' my_param='aaa' # will commit
salt '*' net.load_template my_template template_path='/tmp/tpl/' my_param='aaa' test=True # dry run
salt '*' net.load_template salt://templates/my_stuff.jinja debug=True # equivalent of the next command
salt '*' net.load_template my_stuff.jinja template_path=salt://templates/ debug=True
# in case the template needs to include files that are not under the same path (e.g. http://),
# to help the templating engine find it, you will need to specify the `saltenv` argument:
salt '*' net.load_template my_stuff.jinja template_path=salt://templates saltenv=/path/to/includes debug=True
# render a mako template:
salt '*' net.load_template salt://templates/my_stuff.mako template_engine=mako debug=True
# render remote template
salt -G 'os:junos' net.load_template http://bit.ly/2fReJg7 test=True debug=True peers=['192.168.0.1']
salt -G 'os:ios' net.load_template http://bit.ly/2gKOj20 test=True debug=True peers=['192.168.0.1']
Example output:
{
'comment': '',
'already_configured': False,
'result': True,
'diff': '[edit system]+ host-name edge01.bjm01',
'loaded_config': 'system { host-name edge01.bjm01; }''
}
salt.modules.napalm_network.
mac
(*args, **kwargs)¶Returns the MAC Address Table on the device.
Parameters: |
|
---|---|
Returns: | A list of dictionaries representing the entries in the MAC Address Table |
CLI Example:
salt '*' net.mac
salt '*' net.mac vlan=10
Example output:
[
{
'mac' : '00:1c:58:29:4a:71',
'interface' : 'xe-3/0/2',
'static' : False,
'active' : True,
'moves' : 1,
'vlan' : 10,
'last_move' : 1454417742.58
},
{
'mac' : '8c:60:4f:58:e1:c1',
'interface' : 'xe-1/0/1',
'static' : False,
'active' : True,
'moves' : 2,
'vlan' : 42,
'last_move' : 1453191948.11
}
]
salt.modules.napalm_network.
optics
(*args, **kwargs)¶New in version 2017.7.0.
Fetches the power usage on the various transceivers installed on the network device (in dBm), and returns a view that conforms with the OpenConfig model openconfig-platform-transceiver.yang.
Returns: |
|
---|
CLI Example:
salt '*' net.optics
salt.modules.napalm_network.
ping
(*args, **kwargs)¶Executes a ping on the network device and returns a dictionary as a result.
VRF (routing instance) for ping attempt
New in version 2016.11.4.
CLI Example:
salt '*' net.ping 8.8.8.8
salt '*' net.ping 8.8.8.8 ttl=3 size=65468
salt '*' net.ping 8.8.8.8 source=127.0.0.1 timeout=1 count=100
salt.modules.napalm_network.
rollback
(*args, **kwargs)¶Rollbacks the configuration.
CLI Example:
salt '*' net.rollback
salt.modules.napalm_network.
traceroute
(*args, **kwargs)¶Calls the method traceroute from the NAPALM driver object and returns a dictionary with the result of the traceroute command executed on the device.
VRF (routing instance) for traceroute attempt
New in version 2016.11.4.
CLI Example:
salt '*' net.traceroute 8.8.8.8
salt '*' net.traceroute 8.8.8.8 source=127.0.0.1 ttl=5 timeout=1