From 36004b2657d1c271a5c6c8ddfee0488ad36c1236 Mon Sep 17 00:00:00 2001 From: Sagar Paul Date: Sat, 24 Jul 2021 22:49:38 +0530 Subject: vyos logging_global resource module (#177) vyos logging_global resource module SUMMARY Logging resource module vyos_logging_global ISSUE TYPE New Module Pull Request COMPONENT NAME vyos_logging_global Reviewed-by: Nilashish Chakraborty --- docs/vyos.vyos.vyos_logging_global_module.rst | 1648 +++++++++++++++++++++++++ docs/vyos.vyos.vyos_logging_module.rst | 11 + 2 files changed, 1659 insertions(+) create mode 100644 docs/vyos.vyos.vyos_logging_global_module.rst (limited to 'docs') diff --git a/docs/vyos.vyos.vyos_logging_global_module.rst b/docs/vyos.vyos.vyos_logging_global_module.rst new file mode 100644 index 00000000..0ee25058 --- /dev/null +++ b/docs/vyos.vyos.vyos_logging_global_module.rst @@ -0,0 +1,1648 @@ +.. _vyos.vyos.vyos_logging_global_module: + + +***************************** +vyos.vyos.vyos_logging_global +***************************** + +**Logging resource module** + + +Version added: 2.4.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- This module manages the logging attributes of Vyos network devices + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsComments
+
+ config + +
+ dictionary +
+ 		+ +
A list containing dictionary of logging options
+
+
+ console + +
+ dictionary +
+ 		+ +
logging to serial console
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
facility configurations for console
+
+
+ facility + +
+ string +
+ 		+
    Choices: +
  • all
    • +
  • auth
    • +
  • authpriv
    • +
  • cron
    • +
  • daemon
    • +
  • kern
    • +
  • lpr
    • +
  • mail
    • +
  • mark
    • +
  • news
    • +
  • protocols
    • +
  • security
    • +
  • syslog
    • +
  • user
    • +
  • uucp
    • +
  • local0
    • +
  • local1
    • +
  • local2
    • +
  • local3
    • +
  • local4
    • +
  • local5
    • +
  • local6
    • +
  • local7
    • +
+ 		+
Facility for logging
+
+
+ severity + +
+ string +
+ 		+
    Choices: +
  • emerg
    • +
  • alert
    • +
  • crit
    • +
  • err
    • +
  • warning
    • +
  • notice
    • +
  • info
    • +
  • debug
    • +
  • all
    • +
+ 		+
logging level
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
enable or disable the command
+
+
+ files + +
+ list + / elements=dictionary +
+ 		+ +
logging to file
+
+
+ archive + +
+ dictionary +
+ 		+ +
Log file size and rotation characteristics
+
+
+ file_num + +
+ integer +
+ 		+ +
Number of saved files (default is 5)
+
+
+ size + +
+ integer +
+ 		+ +
Size of log files (in kilobytes, default is 256)
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
enable or disable the command
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
facility configurations
+
+
+ facility + +
+ string +
+ 		+
    Choices: +
  • all
    • +
  • auth
    • +
  • authpriv
    • +
  • cron
    • +
  • daemon
    • +
  • kern
    • +
  • lpr
    • +
  • mail
    • +
  • mark
    • +
  • news
    • +
  • protocols
    • +
  • security
    • +
  • syslog
    • +
  • user
    • +
  • uucp
    • +
  • local0
    • +
  • local1
    • +
  • local2
    • +
  • local3
    • +
  • local4
    • +
  • local5
    • +
  • local6
    • +
  • local7
    • +
+ 		+
Facility for logging
+
+
+ severity + +
+ string +
+ 		+
    Choices: +
  • emerg
    • +
  • alert
    • +
  • crit
    • +
  • err
    • +
  • warning
    • +
  • notice
    • +
  • info
    • +
  • debug
    • +
  • all
    • +
+ 		+
logging level
+
+
+ path + +
+ string +
+ 		+ +
file name or path
+
+
+ global_params + +
+ dictionary +
+ 		+ +
logging to serial console
+
+
+ archive + +
+ dictionary +
+ 		+ +
Log file size and rotation characteristics
+
+
+ file_num + +
+ integer +
+ 		+ +
Number of saved files (default is 5)
+
+
+ size + +
+ integer +
+ 		+ +
Size of log files (in kilobytes, default is 256)
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
enable or disable the command
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
facility configurations
+
+
+ facility + +
+ string +
+ 		+
    Choices: +
  • all
    • +
  • auth
    • +
  • authpriv
    • +
  • cron
    • +
  • daemon
    • +
  • kern
    • +
  • lpr
    • +
  • mail
    • +
  • mark
    • +
  • news
    • +
  • protocols
    • +
  • security
    • +
  • syslog
    • +
  • user
    • +
  • uucp
    • +
  • local0
    • +
  • local1
    • +
  • local2
    • +
  • local3
    • +
  • local4
    • +
  • local5
    • +
  • local6
    • +
  • local7
    • +
+ 		+
Facility for logging
+
+
+ severity + +
+ string +
+ 		+
    Choices: +
  • emerg
    • +
  • alert
    • +
  • crit
    • +
  • err
    • +
  • warning
    • +
  • notice
    • +
  • info
    • +
  • debug
    • +
  • all
    • +
+ 		+
logging level
+
+
+ marker_interval + +
+ integer +
+ 		+ +
time interval how often a mark message is being sent in seconds (default is 1200)
+
+
+ preserve_fqdn + +
+ boolean +
+ 		+
    Choices: +
  • no
    • +
  • yes
    • +
+ 		+
uses FQDN for logging
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
enable or disable the command
+
+
+ hosts + +
+ list + / elements=dictionary +
+ 		+ +
logging to serial console
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
facility configurations for host
+
+
+ facility + +
+ string +
+ 		+
    Choices: +
  • all
    • +
  • auth
    • +
  • authpriv
    • +
  • cron
    • +
  • daemon
    • +
  • kern
    • +
  • lpr
    • +
  • mail
    • +
  • mark
    • +
  • news
    • +
  • protocols
    • +
  • security
    • +
  • syslog
    • +
  • user
    • +
  • uucp
    • +
  • local0
    • +
  • local1
    • +
  • local2
    • +
  • local3
    • +
  • local4
    • +
  • local5
    • +
  • local6
    • +
  • local7
    • +
+ 		+
Facility for logging
+
+
+ protocol + +
+ string +
+ 		+
    Choices: +
  • udp
    • +
  • tcp
    • +
+ 		+
syslog communication protocol
+
+
+ severity + +
+ string +
+ 		+
    Choices: +
  • emerg
    • +
  • alert
    • +
  • crit
    • +
  • err
    • +
  • warning
    • +
  • notice
    • +
  • info
    • +
  • debug
    • +
  • all
    • +
+ 		+
logging level
+
+
+ hostname + +
+ string +
+ 		+ +
Remote host name or IP address
+
+
+ port + +
+ integer +
+ 		+ +
Destination port (1-65535)
+
+
+ syslog + +
+ dictionary +
+ 		+ +
logging syslog
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • enabled
    • +
  • disabled
    • +
+ 		+
enable or disable the command
+
+
+ users + +
+ list + / elements=dictionary +
+ 		+ +
logging to file
+
+
+ facilities + +
+ list + / elements=dictionary +
+ 		+ +
facility configurations
+
+
+ facility + +
+ string +
+ 		+
    Choices: +
  • all
    • +
  • auth
    • +
  • authpriv
    • +
  • cron
    • +
  • daemon
    • +
  • kern
    • +
  • lpr
    • +
  • mail
    • +
  • mark
    • +
  • news
    • +
  • protocols
    • +
  • security
    • +
  • syslog
    • +
  • user
    • +
  • uucp
    • +
  • local0
    • +
  • local1
    • +
  • local2
    • +
  • local3
    • +
  • local4
    • +
  • local5
    • +
  • local6
    • +
  • local7
    • +
+ 		+
Facility for logging
+
+
+ severity + +
+ string +
+ 		+
    Choices: +
  • emerg
    • +
  • alert
    • +
  • crit
    • +
  • err
    • +
  • warning
    • +
  • notice
    • +
  • info
    • +
  • debug
    • +
  • all
    • +
+ 		+
logging level
+
+
+ username + +
+ string +
+ 		+ +
user login name
+
+
+ running_config + +
+ string +
+ 		+ +
This option is used only with state parsed.
+
The value of this option should be the output received from the VYOS device by executing the command show configuration commands | grep syslog.
+
The state parsed reads the configuration from running_config option and transforms it into Ansible structured data as per the resource module's argspec and the value is then returned in the parsed key within the result.
+
+
+ state + +
+ string +
+ 		+
    Choices: +
  • merged ←
    • +
  • replaced
    • +
  • overridden
    • +
  • deleted
    • +
  • gathered
    • +
  • parsed
    • +
  • rendered
    • +
+ 		+
The state the configuration should be left in
+
The states replaced and overridden have identical behaviour for this module.
+
Refer to examples for more details.
+
+
+ + +Notes +----- + +.. note:: + - Tested against vyos 1.2 + - This module works with connection ``network_cli``. + - The Configuration defaults of the Vyos network devices are supposed to hinder idempotent behavior of plays + + + +Examples +-------- + +.. code-block:: yaml + + # Using state: merged + + # Before state: + # ------------- + + # vyos:~$show configuration commands | grep syslog + + - name: Apply the provided configuration + vyos.vyos.vyos_logging_global: + config: + console: + facilities: + - facility: local7 + severity: err + files: + - path: logFile + archive: + file_num: 2 + facilities: + - facility: local6 + severity: emerg + hosts: + - hostname: 172.16.0.1 + facilities: + - facility: local7 + severity: all + - facility: all + protocol: udp + port: 223 + users: + - username: vyos + facilities: + - facility: local7 + severity: debug + global_params: + archive: + file_num: 2 + size: 111 + facilities: + - facility: cron + severity: debug + marker_interval: 111 + preserve_fqdn: true + state: merged + + # Commands Fired: + # --------------- + + # "commands": [ + # "set system syslog console facility local7 level err", + # "set system syslog file logFile archive file 2", + # "set system syslog host 172.16.0.1 facility local7 level all", + # "set system syslog file logFile facility local6 level emerg", + # "set system syslog host 172.16.0.1 facility all protocol udp", + # "set system syslog user vyos facility local7 level debug", + # "set system syslog host 172.16.0.1 port 223", + # "set system syslog global facility cron level debug", + # "set system syslog global archive file 2", + # "set system syslog global archive size 111", + # "set system syslog global marker interval 111", + # "set system syslog global preserve-fqdn" + # ], + + # After state: + # ------------ + + # vyos:~$ show configuration commands | grep syslog + # set system syslog console facility local7 level 'err' + # set system syslog file logFile archive file '2' + # set system syslog file logFile facility local6 level 'emerg' + # set system syslog global archive file '2' + # set system syslog global archive size '111' + # set system syslog global facility cron level 'debug' + # set system syslog global marker interval '111' + # set system syslog global preserve-fqdn + # set system syslog host 172.16.0.1 facility all protocol 'udp' + # set system syslog host 172.16.0.1 facility local7 level 'all' + # set system syslog host 172.16.0.1 port '223' + # set system syslog user vyos facility local7 level 'debug' + + # Using state: deleted + + # Before state: + # ------------- + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility local7 level 'err' + # set system syslog file logFile archive file '2' + # set system syslog file logFile facility local6 level 'emerg' + # set system syslog global archive file '2' + # set system syslog global archive size '111' + # set system syslog global facility cron level 'debug' + # set system syslog global marker interval '111' + # set system syslog global preserve-fqdn + # set system syslog host 172.16.0.1 facility all protocol 'udp' + # set system syslog host 172.16.0.1 facility local7 level 'all' + # set system syslog host 172.16.0.1 port '223' + # set system syslog user vyos facility local7 level 'debug' + + - name: delete the existing configuration + vyos.vyos.vyos_logging_global: + state: deleted + + # Commands Fired: + # --------------- + + # "commands": [ + # "delete system syslog" + # ], + + # After state: + # ------------ + + # vyos:~$show configuration commands | grep syslog + + # Using state: overridden + + # Before state: + # ------------- + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility local7 level 'err' + # set system syslog file logFile archive file '2' + # set system syslog file logFile facility local6 level 'emerg' + # set system syslog global archive file '2' + # set system syslog global archive size '111' + # set system syslog global facility cron level 'debug' + # set system syslog global marker interval '111' + # set system syslog global preserve-fqdn + # set system syslog host 172.16.0.1 facility all protocol 'udp' + # set system syslog host 172.16.0.1 facility local7 level 'all' + # set system syslog host 172.16.0.1 port '223' + # set system syslog user vyos facility local7 level 'debug' + + - name: Override the current configuration + vyos.vyos.vyos_logging_global: + config: + console: + facilities: + - facility: all + - facility: local7 + severity: err + - facility: news + severity: debug + files: + - path: logFileNew + hosts: + - hostname: 172.16.0.2 + facilities: + - facility: local5 + severity: all + global_params: + archive: + file_num: 10 + state: overridden + + # Commands Fired: + # --------------- + + # "commands": [ + # "delete system syslog file logFile", + # "delete system syslog global facility cron", + # "delete system syslog host 172.16.0.1", + # "delete system syslog user vyos", + # "set system syslog console facility all", + # "set system syslog console facility news level debug", + # "set system syslog file logFileNew", + # "set system syslog host 172.16.0.2 facility local5 level all", + # "set system syslog global archive file 10", + # "delete system syslog global archive size 111", + # "delete system syslog global marker", + # "delete system syslog global preserve-fqdn" + # ], + + # After state: + # ------------ + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility all + # set system syslog console facility local7 level 'err' + # set system syslog console facility news level 'debug' + # set system syslog file logFileNew + # set system syslog global archive file '10' + # set system syslog host 172.16.0.2 facility local5 level 'all' + + # Using state: replaced + + # Before state: + # ------------- + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility all + # set system syslog console facility local7 level 'err' + # set system syslog console facility news level 'debug' + # set system syslog file logFileNew + # set system syslog global archive file '10' + # set system syslog host 172.16.0.2 facility local5 level 'all' + + - name: Replace with the provided configuration + register: result + vyos.vyos.vyos_logging_global: + config: + console: + facilities: + - facility: local6 + users: + - username: paul + facilities: + - facility: local7 + severity: err + state: replaced + + # Commands Fired: + # --------------- + + # "commands": [ + # "delete system syslog console facility all", + # "delete system syslog console facility local7", + # "delete system syslog console facility news", + # "delete system syslog file logFileNew", + # "delete system syslog global archive file 10", + # "delete system syslog host 172.16.0.2", + # "set system syslog console facility local6", + # "set system syslog user paul facility local7 level err" + # ], + + # After state: + # ------------ + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility local6 + # set system syslog user paul facility local7 level 'err' + + # Using state: gathered + + - name: Gather logging config + vyos.vyos.vyos_logging_global: + state: gathered + + # Module Execution Result: + # ------------------------ + + # "gathered": { + # "console": { + # "facilities": [ + # { + # "facility": "local6" + # }, + # { + # "facility": "local7", + # "severity": "err" + # } + # ] + # }, + # "files": [ + # { + # "archive": { + # "file_num": 2 + # }, + # "facilities": [ + # { + # "facility": "local6", + # "severity": "emerg" + # } + # ], + # "path": "logFile" + # } + # ], + # "global_params": { + # "archive": { + # "file_num": 2, + # "size": 111 + # }, + # "facilities": [ + # { + # "facility": "cron", + # "severity": "debug" + # } + # ], + # "marker_interval": 111, + # "preserve_fqdn": true + # }, + # "hosts": [ + # { + # "facilities": [ + # { + # "facility": "all", + # "protocol": "udp" + # }, + # { + # "facility": "local7", + # "severity": "all" + # } + # ], + # "hostname": "172.16.0.1", + # "port": 223 + # } + # ], + # "users": [ + # { + # "facilities": [ + # { + # "facility": "local7", + # "severity": "err" + # } + # ], + # "username": "paul" + # }, + # { + # "facilities": [ + # { + # "facility": "local7", + # "severity": "debug" + # } + # ], + # "username": "vyos" + # } + # ] + # }, + + # After state: + # ------------ + + # vyos:~$show configuration commands | grep syslog + # set system syslog console facility local6 + # set system syslog console facility local7 level 'err' + # set system syslog file logFile archive file '2' + # set system syslog file logFile facility local6 level 'emerg' + # set system syslog global archive file '2' + # set system syslog global archive size '111' + # set system syslog global facility cron level 'debug' + # set system syslog global marker interval '111' + # set system syslog global preserve-fqdn + # set system syslog host 172.16.0.1 facility all protocol 'udp' + # set system syslog host 172.16.0.1 facility local7 level 'all' + # set system syslog host 172.16.0.1 port '223' + # set system syslog user paul facility local7 level 'err' + # set system syslog user vyos facility local7 level 'debug' + + # Using state: rendered + + - name: Render the provided configuration + vyos.vyos.vyos_logging_global: + config: + console: + facilities: + - facility: local7 + severity: err + files: + - path: logFile + archive: + file_num: 2 + facilities: + - facility: local6 + severity: emerg + hosts: + - hostname: 172.16.0.1 + facilities: + - facility: local7 + severity: all + - facility: all + protocol: udp + port: 223 + users: + - username: vyos + facilities: + - facility: local7 + severity: debug + global_params: + archive: + file_num: 2 + size: 111 + facilities: + - facility: cron + severity: debug + marker_interval: 111 + preserve_fqdn: true + state: rendered + + # Module Execution Result: + # ------------------------ + + # "rendered": [ + # "set system syslog console facility local7 level err", + # "set system syslog file logFile facility local6 level emerg", + # "set system syslog file logFile archive file 2", + # "set system syslog host 172.16.0.1 facility local7 level all", + # "set system syslog host 172.16.0.1 facility all protocol udp", + # "set system syslog host 172.16.0.1 port 223", + # "set system syslog user vyos facility local7 level debug", + # "set system syslog global facility cron level debug", + # "set system syslog global archive file 2", + # "set system syslog global archive size 111", + # "set system syslog global marker interval 111", + # "set system syslog global preserve-fqdn" + # ] + + # Using state: parsed + + # File: parsed.cfg + # ---------------- + + # set system syslog console facility local6 + # set system syslog console facility local7 level 'err' + # set system syslog file logFile archive file '2' + # set system syslog file logFile facility local6 level 'emerg' + # set system syslog global archive file '2' + # set system syslog global archive size '111' + # set system syslog global facility cron level 'debug' + # set system syslog global marker interval '111' + # set system syslog global preserve-fqdn + # set system syslog host 172.16.0.1 facility all protocol 'udp' + # set system syslog host 172.16.0.1 facility local7 level 'all' + # set system syslog host 172.16.0.1 port '223' + # set system syslog user paul facility local7 level 'err' + # set system syslog user vyos facility local7 level 'debug' + + - name: Parse the provided configuration + vyos.vyos.vyos_logging_global: + running_config: "{{ lookup('file', 'parsed_vyos.cfg') }}" + state: parsed + + # Module Execution Result: + # ------------------------ + + # "parsed": { + # "console": { + # "facilities": [ + # { + # "facility": "local6" + # }, + # { + # "facility": "local7", + # "severity": "err" + # } + # ] + # }, + # "files": [ + # { + # "archive": { + # "file_num": 2 + # }, + # "facilities": [ + # { + # "facility": "local6", + # "severity": "emerg" + # } + # ], + # "path": "logFile" + # } + # ], + # "global_params": { + # "archive": { + # "file_num": 2, + # "size": 111 + # }, + # "facilities": [ + # { + # "facility": "cron", + # "severity": "debug" + # } + # ], + # "marker_interval": 111, + # "preserve_fqdn": true + # }, + # "hosts": [ + # { + # "facilities": [ + # { + # "facility": "all", + # "protocol": "udp" + # }, + # { + # "facility": "local7", + # "severity": "all" + # } + # ], + # "hostname": "172.16.0.1", + # "port": 223 + # } + # ], + # "users": [ + # { + # "facilities": [ + # { + # "facility": "local7", + # "severity": "err" + # } + # ], + # "username": "paul" + # }, + # { + # "facilities": [ + # { + # "facility": "local7", + # "severity": "debug" + # } + # ], + # "username": "vyos" + # } + # ] + # } + # } + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this module: + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ after + +
+ dictionary +
+ 		when changed +
The resulting configuration after module execution.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ before + +
+ dictionary +
+ 		when state is merged, replaced, overridden, deleted or purged +
The configuration prior to the module execution.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ commands + +
+ list +
+ 		when state is merged, replaced, overridden, deleted or purged +
The set of commands pushed to the remote device.
+
+
Sample:
+
['set system syslog console facility local7 level err', 'set system syslog host 172.16.0.1 port 223', 'set system syslog global archive size 111']
+
+
+ gathered + +
+ list +
+ 		when state is gathered +
Facts about the network resource gathered from the remote device as structured data.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ parsed + +
+ list +
+ 		when state is parsed +
The device native config provided in running_config option parsed into structured data as per module argspec.
+
+
Sample:
+
This output will always be in the same format as the module argspec.
+
+
+ rendered + +
+ list +
+ 		when state is rendered +
The provided configuration in the task rendered in device-native format (offline).
+
+
Sample:
+
['set system syslog host 172.16.0.1 port 223', 'set system syslog user vyos facility local7 level debug', 'set system syslog global facility cron level debug']
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Sagar Paul (@KB-perByte) diff --git a/docs/vyos.vyos.vyos_logging_module.rst b/docs/vyos.vyos.vyos_logging_module.rst index 9cb024d0..39f885e9 100644 --- a/docs/vyos.vyos.vyos_logging_module.rst +++ b/docs/vyos.vyos.vyos_logging_module.rst @@ -14,6 +14,13 @@ Version added: 1.0.0 :local: :depth: 1 +DEPRECATED +---------- +:Removed in collection release after 2023-08-01 +:Why: Updated module released with more functionality. +:Alternative: vyos_logging_global + + Synopsis -------- @@ -434,6 +441,10 @@ Status ------ +- This module will be removed in version . *[deprecated]* +- For more information see `DEPRECATED`_. + + Authors ~~~~~~~ -- cgit v1.2.3