Manage the configuration on a network device given a specific static config or template.
codeauthor: | Mircea Ulinic <mircea@cloudflare.com> & Jerome Fleury <jf@cloudflare.com> |
---|---|
maturity: | new |
depends: | napalm |
platform: | unix |
New in version 2017.7.0.
New in version 2019.2.0.
Cancel a commit scheduled to be executed via the commit_in
and commit_at
arguments from the net.load_template
or net.load_config
execution functions. The commit ID is displayed when the commit is scheduled via the functions named above.
State SLS Example:
'20180726083540640360': netconfig.commit_cancelled
New in version 2019.2.0.
Confirm a commit scheduled to be reverted via the revert_in
and revert_at
arguments from the net.load_template
or net.load_config
execution functions. The commit ID is displayed when the commit confirmed is scheduled via the functions named above.
State SLS Example:
'20180726083540640360': netconfig.commit_confirmed
Manages the configuration on network devices.
By default this state will commit the changes on the device. If there are no changes required, it does not commit and the field already_configured
from the output dictionary will be set as True
to notify that.
To avoid committing the configuration, set the argument test
to True
(or via the CLI argument test=True
) and will discard (dry run).
To preserve the changes, set commit
to False
(either as CLI argument, either as state parameter). 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
. This option is recommended to be used with caution!
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
Changed in version 2019.2.0: This argument can now support a list of templates to be rendered. The resulting configuration text is loaded at once, as a single configuration chunk.
{hash_type: 'md5', 'hsum': <md5sum>}
template_hash
refers to a remote file, this specifies the filename to look for in that file.The following templates engines are supported:
If True
, hash verification of remote file sources (http://
, https://
, ftp://
) will be skipped, and the source_hash
argument will be ignored.
Changed in version 2017.7.1.
True
, will apply the config, discard and return the changes. Default: False
(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.
Note
This argument cannot be used directly on the command line. Instead, it can be passed through the pillar
variable when executing either of the state.sls
or state.apply
(see below for an example).
None
Commit the changes in a specific number of minutes / hours. Example of accepted formats: 5
(commit in 5 minutes), 2m
(commit in 2 minutes), 1h
(commit the changes in 1 hour)`, 5h30m
(commit the changes in 5 hours and 30 minutes).
Note
This feature works on any platforms, as it does not rely on the native features of the network operating system.
Note
After the command is executed and the diff
is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the net.cancel_commit
execution function, using the commit ID returned by this function.
Warning
Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile).
New in version 2019.2.0.
None
Commit the changes at a specific time. Example of accepted formats: 1am
(will commit the changes at the next 1AM), 13:20
(will commit at 13:20), 1:20am
, etc.
Note
This feature works on any platforms, as it does not rely on the native features of the network operating system.
Note
After the command is executed and the diff
is not satisfactory, or for any other reasons you have to discard the commit, you are able to do so using the net.cancel_commit
execution function, using the commit ID returned by this function.
Warning
Using this feature, Salt will load the exact configuration you expect, however the diff may change in time (i.e., if an user applies a manual configuration change, or a different process or command changes the configuration in the meanwhile).
New in version 2019.2.0.
None
Commit and revert the changes in a specific number of minutes / hours. Example of accepted formats: 5
(revert in 5 minutes), 2m
(revert in 2 minutes), 1h
(revert the changes in 1 hour)`, 5h30m
(revert the changes in 5 hours and 30 minutes).
Note
To confirm the commit, and prevent reverting the changes, you will have to execute the net.confirm_commit
function, using the commit ID returned by this function.
Warning
This works on any platform, regardless if they have or don't have native capabilities to confirming a commit. However, please be very cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don't have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device.
Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them.
New in version 2019.2.0.
None
Commit and revert the changes at a specific time. Example of accepted formats: 1am
(will commit and revert the changes at the next 1AM), 13:20
(will commit and revert at 13:20), 1:20am
, etc.
Note
To confirm the commit, and prevent reverting the changes, you will have to execute the net.confirm_commit
function, using the commit ID returned by this function.
Warning
This works on any platform, regardless if they have or don't have native capabilities to confirming a commit. However, please be very cautious when using this feature: on Junos (as it is the only NAPALM core platform supporting this natively) it executes a commit confirmed as you would do from the command line. All the other platforms don't have this capability natively, therefore the revert is done via Salt. That means, your device needs to be reachable at the moment when Salt will attempt to revert your changes. Be cautious when pushing configuration changes that would prevent you reach the device.
Similarly, if an user or a different process apply other configuration changes in the meanwhile (between the moment you commit and till the changes are reverted), these changes would be equally reverted, as Salt cannot be aware of them.
New in version 2019.2.0.
False
(will apply load merge).Overrides default context variables passed to the template.
New in version 2019.2.0.
Dictionary with the arguments/context to be used when the template is rendered. Do not explicitly specify this argument. This represents any other variable that will be sent to the template rendering system. Please see an example below! In both ntp_peers_example_using_pillar
and ntp_peers_example
, peers
is sent as template variable.
Note
It is more recommended to use the context
argument instead, to avoid any conflicts with other arguments.
SLS Example (e.g.: under salt://router/config.sls) :
whole_config_example: netconfig.managed: - template_name: salt://path/to/complete_config.jinja - debug: True - replace: True bgp_config_example: netconfig.managed: - template_name: /absolute/path/to/bgp_neighbors.mako - template_engine: mako prefix_lists_example: netconfig.managed: - template_name: prefix_lists.cheetah - debug: True - template_engine: cheetah ntp_peers_example: netconfig.managed: - template_name: http://bit.ly/2gKOj20 - skip_verify: False - debug: True - peers: - 192.168.0.1 - 192.168.0.1 ntp_peers_example_using_pillar: netconfig.managed: - template_name: http://bit.ly/2gKOj20 - peers: {{ pillar.get('ntp.peers', []) }}
Multi template example:
hostname_and_ntp: netconfig.managed: - template_name: - https://bit.ly/2OhSgqP - https://bit.ly/2M6C4Lx - https://bit.ly/2OIWVTs - debug: true - context: hostname: {{ opts.id }} servers: - 172.17.17.1 - 172.17.17.2 peers: - 192.168.0.1 - 192.168.0.2
Usage examples:
$ sudo salt 'juniper.device' state.sls router.config test=True $ sudo salt -N all-routers state.sls router.config pillar="{'debug': True}"
router.config
depends on the location of the SLS file (see above). Running this command, will be executed all five steps from above. These examples above are not meant to be used in a production environment, their sole purpose is to provide usage examples.
Output example:
$ sudo salt 'juniper.device' state.sls router.config test=True juniper.device: ---------- ID: ntp_peers_example_using_pillar Function: netconfig.managed Result: None Comment: Testing mode: Configuration discarded. Started: 12:01:40.744535 Duration: 8755.788 ms Changes: ---------- diff: [edit system ntp] peer 192.168.0.1 { ... } + peer 172.17.17.1; + peer 172.17.17.3; Summary for juniper.device ------------ Succeeded: 1 (unchanged=1, changed=1) Failed: 0 ------------ Total states run: 1 Total run time: 8.756 s
Raw output example (useful when the output is reused in other states/execution modules):
$ sudo salt --out=pprint 'juniper.device' state.sls router.config test=True debug=True
{ 'juniper.device': { 'netconfig_|-ntp_peers_example_using_pillar_|-ntp_peers_example_using_pillar_|-managed': { '__id__': 'ntp_peers_example_using_pillar', '__run_num__': 0, 'already_configured': False, 'changes': { 'diff': '[edit system ntp] peer 192.168.0.1 { ... }+ peer 172.17.17.1;+ peer 172.17.17.3;' }, 'comment': 'Testing mode: Configuration discarded.', 'duration': 7400.759, 'loaded_config': 'system { ntp { peer 172.17.17.1; peer 172.17.17.3; } }', 'name': 'ntp_peers_example_using_pillar', 'result': None, 'start_time': '12:09:09.811445' } } }
New in version 2019.2.0.
Replace occurrences of a pattern in the configuration source. If show_changes
is True
, then a diff of what changed will be returned, otherwise a True
will be returned when changes are made, and False
when no changes are made. This is a pure Python implementation that wraps Python's sub()
.
search()
.0
n
, only n
occurrences will be replaced, otherwise all occurrences will be replaced.8
re
module documentation from the Python standard library. Each list item should be a string that will correlate to the human-friendly flag name. E.g., ['IGNORECASE',
'MULTILINE']
. Optionally, flags
may be an int, with a value corresponding to the XOR (|
) of all the desired flags. Defaults to 8 (which supports 'MULTILINE').1
1
processes one line at a time. The special value file
may be specified which will read the entire file into memory before processing.False
True
, and pattern is not found, then the content will be appended to the file.False
True
and pattern is not found, then the content will be prepended to the file.repl
. Useful when repl
uses references to group in pattern.False
True
if the pattern was matched, and False
if not.True
True
, return a diff of changes made. Otherwise, return True
if changes were made, and False
if not.False
running
running
, candidate
, or startup
. Default: running
.False
True
, will apply the config, discard and return the changes. Default: False
and will commit the changes on the device.True
True
.False
loaded_config
containing the raw configuration loaded on the device.True
True
.If an equal sign (=
) appears in an argument to a Salt command it is interpreted as a keyword argument in the format key=val
. That processing can be bypassed in order to pass an equal sign through to the remote shell command by manually specifying the kwarg:
State SLS Example:
update_policy_name: netconfig.replace_pattern: - pattern: OLD-POLICY-NAME - repl: new-policy-name - debug: true
New in version 2019.2.0.
Save the configuration to a file on the local file system.
cp.push
Execution function.running
running
, candidate
, startup
. Default: running
.The permissions to set on this file, e.g. 644
, 0775
, or 4664
. The default mode for new files and directories corresponds to the umask of the salt process. The mode of existing files and directories will only be changed if mode
is specified.
Note
This option is not supported on Windows.
The attributes to have on this file, e.g. a
, i
. The attributes can be any or a combination of the following characters: aAcCdDeijPsStTu
.
Note
This option is not supported on Windows.
False
True
, then the parent directories will be created to facilitate the creation of the named file. If False
, and the parent directory of the destination file doesn't exist, the state will fail.If directories are to be created, passing this option specifies the permissions for those directories. If this is not set, directories will be assigned permissions by adding the execute bit to the mode of the files.
The default mode for new files and directories corresponds umask of salt process. For existing files and directories it's not enforced.
True
False
and the file already exists, the file will not be modified even if changes would otherwise be made. Permissions and ownership will still be enforced, however.True
False
return a boolean if any changes were made.True
False
, then the file will only be managed if the file already exists on the system.'strict'
`'strict'`
. See https://docs.python.org/2/library/codecs.html#codec-base-classes for the list of available schemes.True
False
, then the state will fail if the contents specified by contents_pillar
or contents_grains
are empty.True
check_cmd
. Useful for checkers dependent on config file location (e.g. daemons restricted to their own config directories by an apparmor profile).check_cmd
. Useful for checkers dependent on config file extension (e.g. the init-checkconf upstart config checker).None
None
{'Administrators': {'perms': 'full_control'}}
Can be a single basic perm or a list of advanced perms. perms
must be specified. applies_to
does not apply to file objects.None
{'Administrators': {'perms': 'full_control'}}
Can be a single basic perm or a list of advanced perms. perms
must be specified. applies_to
does not apply to file objects.True
False
True
the existing DACL will be cleared and replaced with the settings defined in this function. If False
, new entries will be appended to the existing DACL. Default is False
.State SLS Example:
/var/backups/{{ opts.id }}/{{ salt.status.time('%s') }}.cfg: netconfig.saved: - source: running - makedirs: true
The state SLS above would create a backup config grouping the files by the Minion ID, in chronological files. For example, if the state is executed at on the 3rd of August 2018, at 5:15PM, on the Minion core1.lon01
, the configuration would saved in the file: /var/backups/core01.lon01/1533316558.cfg
© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/states/all/salt.states.netconfig.html