diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/commandscripting.rst | 107 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 371 | ||||
| -rw-r--r-- | docs/high-availability.rst | 120 | ||||
| -rw-r--r-- | docs/index.rst | 10 | ||||
| -rw-r--r-- | docs/system/index.rst | 1 | ||||
| -rw-r--r-- | docs/system/syslog.rst | 63 | ||||
| -rw-r--r-- | docs/system/systemusers.rst | 22 | ||||
| -rw-r--r-- | docs/system/task-scheduler.rst | 60 | ||||
| -rw-r--r-- | docs/troubleshooting.rst | 142 |
9 files changed, 878 insertions, 18 deletions
diff --git a/docs/commandscripting.rst b/docs/commandscripting.rst new file mode 100644 index 00000000..cfdbae44 --- /dev/null +++ b/docs/commandscripting.rst @@ -0,0 +1,107 @@ +.. _commandscripting: + + +Command scripting +================= + +VyOS supports executing configuration and operational commands non-interactively from shell scripts. + +To include VyOS-specific functions and aliases you need to ``source /opt/vyatta/etc/functions/script-template`` files at the top of your script. + +.. code-block:: sh + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + + exit + +Run configuration commands +-------------------------- + +Configuration commands are executed just like from a normal config session. + +For example, if you want to disable a BGP peer on VRRP transition to backup: + +.. code-block:: sh + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + + configure + + set protocols bgp 65536 neighbor 192.168.2.1 shutdown + + commit + + exit + + +Run operational commands +------------------------ + +Unlike a normal configuration sessions, all operational commands must be prepended with ``run``, even if you haven't created a session with configure. + +.. code-block:: sh + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + + run show interfaces + + exit + +Other script language +--------------------- + +If you want to script the configs in a language other than bash you can have your script output commands and then source them in a bash script. + +Here is a simple example: + +.. code-block:: python + + #!/usr/bin/env python + print "delete firewall group address-group somehosts" + print "set firewall group address-group somehosts address '1.1.1.1'" + print "set firewall group address-group somehosts address '1.1.1.2'" + + +.. code-block:: sh + + #!bin/vbash + source /opt/vyatta/etc/functions/script-template + + configure + source <(/config/scripts/setfirewallgroup.py) + commit + + +Executing Configuration Scripts +------------------------------- + +There is a pitfall when working with configuration scripts. It is tempting to call configuration scripts with "sudo" (i.e., temporary root permissions), because that's the common way on most Linux platforms to call system commands. + +On VyOS this will cause the following problem: After modifying the configuration via script like this once, it is not possible to manually modify the config anymore: + +.. code-block:: sh + + sudo ./myscript.sh # Modifies config + configure + set ... # Any configuration parameter + +| This will result in the following error message: ``Set failed`` +| If this happens, a reboot is required to be able to edit the config manually again. + +To avoid these problems, the proper way is to call a script with the ``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: + +.. code-block:: sh + + sg vyattacfg -c ./myscript.sh + + +To make sure that a script is not accidentally called without the ``vyattacfg`` group, the script can be safeguarded like this: + +.. code-block:: sh + + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi
\ No newline at end of file diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..d3c5cb57 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,371 @@ +.. _contributing_index: + + +Bug Reports and Feature Requests +================================ + +For Bug Reports and Feature Requests please take a look at Phabricator here: + +https://phabricator.vyos.net + + +Bug Report +---------- + +| To create a Bugreport use the quick link in the left side under the specific project. +| Please think about the next points: + + * provide as much information as you can + * which version you use + * what is to do to reproduce the bug + + +Feature Request +--------------- + +To send a Feature Request please search in Phabricator if there is already a Feature Request. You can enhance it or if you don't find one create a new one by use the quick link in the left side under the specific project. + + +Development +=========== + +The source code is hosted on github under VyOS organization: `github.com/vyos`_ + +The code is split into git submodules. Submodules is a mechanism for keeping subprojects in separate git repos while being able to access them from the main project. + +VyOS is composed of multiple individual packages, some of them are periodically synced with upstream, so keeping the whole source under a single repository would be very inconvenient and slow. There is now an ongoing effort to consolidate all VyOS-specific packages into vyos-1x package, but the basic structure is going to stay the same, just with fewer submodules. + +The repository that contains the ISO build scripts and links to all submodules is vyos-build_. The README will guide you to use the this toplevel repository. + + +VyOS CLI +======== + +The bash completion in VyOS is defined in *templates*. Templates are text files stored in a directory tree, where directory names define command names, and template files define command behaviour. +Befor VyOS 1.2.x this files were created by hand. After a complex redesing process_ the new style template are in XML. + +| XML interface definitions for VyOS come with a RelaxNG schema and are located here vyos-1x_ +| This schema is a slightly modified schema from VyConf_ alias VyOS 2.0 +| So VyOS 1.2.x interface definitions will be reusable in Nextgen VyOS Versions with very minimal changes. + +The great thing about schemas is not only that people can know the complete grammar for certain, but also that it can be automatically verified. +The scripts/build-command-templates script that converts the XML definitions to old style templates also verifies them against the schema, so a bad definition will cause the package build to fail. +I do agree that the format is verbose, but there is no other format now that would allow this. Besides, a specialized XML editor can alleviate the issue with verbosity. + +Example XML File +---------------- + + +.. code-block:: xml + + <?xml version="1.0"?> + <!-- Cron configuration --> + <interfaceDefinition> + <node name="system"> + <children> + <node name="task-scheduler"> + <properties> + <help>Task scheduler settings</help> + </properties> + <children> + <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> + <properties> + <help>Scheduled task</help> + <valueHelp> + <format><string></format> + <description>Task name</description> + </valueHelp> + <priority>999</priority> + </properties> + <children> + <leafNode name="crontab-spec"> + <properties> + <help>UNIX crontab time specification string</help> + </properties> + </leafNode> + <leafNode name="interval"> + <properties> + <help>Execution interval</help> + <valueHelp> + <format><minutes></format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><minutes>m</format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><hours>h</format> + <description>Execution interval in hours</description> + </valueHelp> + <valueHelp> + <format><days>d</format> + <description>Execution interval in days</description> + </valueHelp> + <constraint> + <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> + </constraint> + </properties> + </leafNode> + <node name="executable"> + <properties> + <help>Executable path and arguments</help> + </properties> + <children> + <leafNode name="path"> + <properties> + <help>Path to executable</help> + </properties> + </leafNode> + <leafNode name="arguments"> + <properties> + <help>Arguments passed to the executable</help> + </properties> + </leafNode> + </children> + </node> + </children> + </tagNode> + </children> + </node> + </children> + </node> + </interfaceDefinition> + +Configuration mode command definitions +-------------------------------------- + +Command definitions are purely declarative, and cannot contain any logic. All logic for generating config files for target applications, restarting services and so on is implemented in configuration scripts instead. + +Command syntax guidelines +************************* + +Use of numbers +^^^^^^^^^^^^^^ + +Use of numbers in command names **should** be avoided unless a number is a part of a protocol name or similar. Thus, "protocols ospfv3" is perfectly fine, but something like "server-1" is questionable at best. + + +Help string guidelines +********************** + +To ensure uniform look and feel, and improve readability, we should follow a set of guidelines consistently. + +Capitalization and punctuation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first word of every help string **must** be capitalized. There **must not** be a period at the end of help strings. Rationale: this seems to be the unwritten standard in network device CLIs, and a good aesthetic compromise. + +Examples: + + * Good: "Frobnication algorithm" + * Bad: "frobnication algorithm" + * Bad: "Frobnication algorithm." + * Horrible: "frobnication algorithm." + +Use of abbreviations and acronyms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Abbreviations and acronyms **must** be capitalized. + +Examples: + + * Good: "TCP connection timeout" + * Bad: "tcp connection timeout" + * Horrible: "Tcp connectin timeout" + +Acronyms also **must** be capitalized to visually distinguish them from normal words: + +Examples: + + * Good: RADIUS (as in remote authentication for dial-in user services) + * Bad: radius (unless it's about the distance between a center of a circle and any of its points) + +Some abbreviations are traditionally written in mixed case. Generally, if it contains words "over" or "version", the letter **should** be lowercase. If there's an accepted spelling (especially if defined by an RFC or another standard), it **must** be followed. + +Examples: + + * Good: PPPoE, IPsec + * Bad: PPPOE, IPSEC + * Bad: pppoe, ipsec + +Use of verbs +^^^^^^^^^^^^ + +Verbs **should** be avoided. If a verb can be omitted, omit it. + +Examples: + + * Good: "TCP connection timeout" + * Bad: "Set TCP connection timeout" + +If a verb is essential, keep it. For example, in the help text of "set system ipv6 disable-forwarding", "Disable IPv6 forwarding on all interfaces" is a perfectly justified wording. + +Prefer infinitives +^^^^^^^^^^^^^^^^^^ + +Verbs, when they are necessary, **should** be in their infinitive form. + +Examples: + + * Good: "Disable IPv6 forwarding" + * Bad: "Disables IPv6 forwarding" + + +Mapping from the old node.def style to the new XML definitions +-------------------------------------------------------------- + + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Old concept/syntax + - New syntax + - Notes + * - mynode/node.def + - <node name="mynode"> </node> + - Leaf nodes (nodes with values) use <leafNode> tag instead + * - mynode/node.tag , tag: + - <tagNode name="mynode> </node> + - + * - help: My node + - <properties> <help>My node</help> + - + * - val_help: <format>; some string + - <properties> <valueHelp> <format> format </format> <description> some string </description> + - Do not add angle brackets around the format, they will be inserted automatically + * - syntax:expression: pattern + - <properties> <constraint> <regex> ... + - <constraintErrorMessage> will be displayed on failure + * - syntax:expression: $VAR(@) in "foo", "bar", "baz" + - None + - Use regex + * - syntax:expression: exec ... + - <properties> <constraint> <validator> <name ="foo" argument="bar"> + - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, <constraintErrorMessage> will be displayed on failure + * - syntax:expression: (arithmetic expression) + - None + - External arithmetic validator may be added if there's demand, complex validation is better left to commit-time scripts + * - priority: 999 + - <properties> <priority>999</priority> + - Please leave a comment explaining why the priority was chosen (e.g. "after interfaces are configured") + * - multi: + - <properties> <multi/> + - Only applicable to leaf nodes + * - allowed: echo foo bar + - <properties> <completionHelp> <list> foo bar </list> + - + * - allowed: cli-shell-api listNodes vpn ipsec esp-group + - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ... + - + * - allowed: /path/to/script + - <properties> <completionHelp> <script> /path/to/script </script> ... + - + * - default: + - None + - Move default values to scripts + * - commit:expression: + - None + - All commit time checks should be in the verify() function of the script + * - begin:/create:/delete: + - None + - All logic should be in the scripts + +Python coding guidelines +======================== + +The switch to the Python programming language for new code is not merely a change of the language, but a chance to rethink and improve the programming approach. + +Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS config, generating daemon configs, and restarting processes is all mixed up. +Python (or any other language, for that matter) does not provide automatic protection from bad design, so we need to also devise design guidelines and follow them to keep the system extensible and maintainable. + +Configuration script structure and behaviour +-------------------------------------------- + +.. code-block:: python + + import sys + + from vyos.config import Config + from vyos.util import ConfigError + + + def get_config(): + vc = Config() + # Convert the VyOS config to an abstract internal representation + config = ... + return config + + def verify(config): + # Verify that configuration is valid + if invalid: + raise ConfigError("Descriptive message") + return True + + def generate(config): + # Generate daemon configs + pass + + def apply(config): + # Apply the generated configs to the live system + pass + + try: + config = get_config() + verify(config) + except ConfigError as e: + print(e) + sys.exit(1) + +The **get_config()** function must convert the VyOS config to an abstract internal representation. No other function is allowed to call vyos.config.Config object methods directly. The rationale for it is that when config reads are mixed with other logic, it's very hard to change the config syntax since you need to weed out every occurence of the old syntax. If syntax-specific code is confined to a single function, the rest of the code can be left untouched as long as the internal representation remains compatible. + +Another advantage is testability of the code. Mocking the entire config subsystem is hard, while constructing an internal representation by hand is way simpler. + +The **verify()** function takes an internal representation of the config and checks if it's valid, otherwise it must raise VyOSError with an error message that describes the problem and possibly suggests how to fix it. It must not make any changes to the system. The rationale for it is again testability and, in the future when the config backend is ready and every script is rewritten in this fashion, ability to execute commit dry run ("commit test" like in JunOS) and abort commit before making any changes to the system if an error is found in any component. + +The **generate()** function generates config files for system components. + +The **apply()** function applies the generated configuration to the live system. It should use non-disruptive reload whenever possible. It may execute disruptive operations such as daemon process restart if a particular component does not support non-disruptive reload, or when the expected service degradation is minimal (for example, in case of auxillary services such as LLDPd). In case of high impact services such as VPN daemon and routing protocols, when non-disruptive reload is supported for some but not all types of configuration changes, scripts authors should make effort to determine if a configuration change can be done in a non-disruptive way and only resort to disruptive restart if it cannot be avoided. + +Unless absolutely necessary, configuration scripts should not modify the active configuration of system components directly. Whenever at all possible, scripts should generate a configuration file or files that can be applied with a single command such as reloading a service through systemd/SysV init. Inserting statements one by one is particularly discouraged, for example, when configuring netfilter rules, saving them to a file and loading it with iptables-restore should always be preferred to executing iptables directly. + +The **apply()** and **generate()** functions may raise ConfigError if, for example, the daemon failed to start with the updated config. It shouldn't be a substitute for proper config checking in the **verify()** function. All reasonable effort should be made to verify that generated configuration is valid and will be accepted by the daemon, including, when necessary, cross-checks with other VyOS configuration subtrees. + +Exceptions, including VyOSError (which is raised by vyos.config.Config on improper config operations, such as trying to use **list_nodes()** on a non-tag node) should not be silenced or caught and re-raised as config error. Sure this will not look pretty on user's screen, but it will make way better bug reports, and help users (and most VyOS users are IT professionals) do their own debugging as well. + +Coding guidelines +----------------- + +Language +******** + +| Python 3 **shall** be used. How long can we keep Python 2 alive anyway? +| No considerations for Python 2 compatibility **should** be taken. + +Formatting +********** + +Tabs **shall not** be used. Every indentation level should be 4 spaces. + +Text generation +*************** + +| Template processor **should** be used for generating config files. Built-in string formatting **may** be used for simple line-oriented formats where every line is self-contained, such as iptables rules. Template processor **must** be used for structured, multi-line formats such as those used by ISC DHCPd. +| The default template processor for VyOS code is jinja2. + +Code policy +----------- + +When modifying the source code, remember these rules of the legacy elimination campaign: + + * No new features in Perl + * No old style command definitions + * No code incompatible with Python3 + + +.. _github.com/vyos: https://github.com/vyos +.. _vyos-build: https://github.com/vyos/vyos-build +.. _process: https://blog.vyos.io/vyos-development-digest-10 +.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/ +.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata diff --git a/docs/high-availability.rst b/docs/high-availability.rst new file mode 100644 index 00000000..c967d647 --- /dev/null +++ b/docs/high-availability.rst @@ -0,0 +1,120 @@ +.. _high-availability: + +High availability +================= + +VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. +Every VRRP router has a physical IP/IPv6 address, and a virtual address. +On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. +If the master fails and stops sending keepalive packets, router with the next highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. +You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). +If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. + +Basic setup +----------- + +VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. +The required parameters are interface, vrid, and virtual-address. + +mininmal config + +.. code-block:: sh + + set high-availability vrrp group Foo vrid 10 + set high-availability vrrp group Foo interface eth0 + set high-availability vrrp group Foo virtual-address 192.0.2.1/24 + +You can verify your VRRP group status with the operational mode ``run show vrrp`` command: + +.. code-block:: sh + + vyos@vyos# run show vrrp + Name Interface VRID State Last Transition + ---------- ----------- ------ ------- ----------------- + Foo eth1 10 MASTER 2s + +IPv6 support +------------ + +The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. + +Disabling a VRRP group +---------------------- + +You can disable a VRRP group with ``disable`` option: + +.. code-block:: sh + + set high-availability vrrp group Foo disable + +A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. + +Setting VRRP group priority +--------------------------- + +VRRP priority can be set with ``priority`` option: + +.. code-block:: sh + + set high-availability vrrp group Foo priority 200 + +The priority must be an interger number from 1 to 255. Higher priority value increases router's precedence in the master elections. + +Preemption +---------- + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indenfinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" option: + +.. code-block:: sh + + set high-availability vrrp group Foo no-preempt + +You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: + +.. code-block:: sh + + set high-availability vrrp group Foo preempt-delay 180 + +Unicast VRRP +------------ + +By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. + +.. code-block:: sh + + set high-availability vrrp group Foo peer-address 192.0.2.10 + set high-availability vrrp group Foo hello-source-address 192.0.2.15 + +Scripting +--------- + +VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. +Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. + +Health check scripts +^^^^^^^^^^^^^^^^^^^^ + +This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: + +.. code-block:: sh + + set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh + set high-availability vrrp group Foo health-check interval 60 + set high-availability vrrp group Foo health-check failure-count 3 + +Transition scripts +^^^^^^^^^^^^^^^^^^ + +Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: + +.. code-block:: sh + + set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo"
\ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 344cd761..fb15e991 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,9 +27,19 @@ as a router and firewall platform for cloud deployments. qos.rst services/index.rst system/index.rst + high-availability.rst clustering.rst image-mgmt.rst + commandscripting.rst troubleshooting.rst examples.rst commandtree/index.rst +.. toctree:: + :maxdepth: 2 + :caption: Contributing: + :includehidden: + + contributing/index.rst + + diff --git a/docs/system/index.rst b/docs/system/index.rst index 368b62ff..d2a3d763 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -16,4 +16,5 @@ should be ready for further configuration which is described in this chapter. host-information systemusers syslog + task-scheduler config-management
\ No newline at end of file diff --git a/docs/system/syslog.rst b/docs/system/syslog.rst index dbf7420a..8acbc237 100644 --- a/docs/system/syslog.rst +++ b/docs/system/syslog.rst @@ -112,3 +112,66 @@ logged in, no messages are being displayed. .. code-block:: sh set system syslog user <LOCAL_USERNAME> facility <FACILITY> level <LEVEL> + +Show logs +^^^^^^^^^ + +Display log files on the console + +.. code-block:: sh + + vyos@vyos:~$ show log + Possible completions: + <Enter> Execute the current command + all Show contents of all master log files + authorization Show listing of authorization attempts + cluster Show log for Cluster + conntrack-sync + Show log for Conntrack-sync + dhcp Show log for Dynamic Host Control Protocol (DHCP) + directory Show listing of user-defined log files + dns Show log for Domain Name Service (DNS) + file Show contents of user-defined log file + firewall Show log for Firewall + https Show log for Https + image Show logs from an image + lldp Show log for Lldp + nat Show log for Network Address Translation (NAT) + openvpn Show log for Openvpn + snmp Show log for Simple Network Monitoring Protocol (SNMP) + tail Monitor last lines of messages file + vpn Show log for Virtual Private Network (VPN) + vrrp Show log for Virtual Router Redundancy Protocol (VRRP) + webproxy Show log for Webproxy + +Show contents of a log file in an image +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Log messages from a specified image can be displayed on the console: + +.. code-block:: sh + + $ show log image <image name> + $ show log image <image name> [all | authorization | directory | file <file name> | tail <lines>] + +Details of allowed parameters: + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file <file name> + - Display contents of a specified user-defined log file of the specified image + * - tail + - Display last lines of the system log of the specified image + * - <lines> + - Number of lines to be displayed, default 10 + + +When no options/parameters are used, the contents of the main syslog file are displayed. diff --git a/docs/system/systemusers.rst b/docs/system/systemusers.rst index a8ae570e..ef153377 100644 --- a/docs/system/systemusers.rst +++ b/docs/system/systemusers.rst @@ -3,31 +3,21 @@ System Users ------------ -VyOS supports two levels of users: admin and operator. +The default vyos user account, as well as newly created user accounts, have all capabilities to configure the system. +All accounts have sudo capabilities and therefore can operate as root on the system. +Setting the level to admin is optional, all accounts on the system +will have admin privileges. -The operator level restricts a user to operational commands and prevents -changes to system configuration. This is useful for gathering information -about the state of the system (dhcp leases, vpn connections, routing tables, -etc...) and for manipulating state of the system, such as resetting -connections, clearing counters and bringing up and taking down connection -oriented interfaces. - -The admin level has all of the capabilities of the operator level, plus the -ability to change system configuration. The admin level also enables a user -to use the sudo command, which essentially means the user has root access to -the system. Creating Login User Accounts ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Create user account `jsmith`, with `admin` level access and the password -`mypassword` +Create user account `jsmith` and the password `mypassword`. .. code-block:: sh set system login user jsmith full-name "Johan Smith" set system login user jsmith authentication plaintext-password mypassword - set system login user jsmith level admin The command: @@ -63,4 +53,4 @@ The following command will load the public key `dev.pub` for user `jsmith` .. code-block:: sh - loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub
\ No newline at end of file + loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub diff --git a/docs/system/task-scheduler.rst b/docs/system/task-scheduler.rst new file mode 100644 index 00000000..73057afd --- /dev/null +++ b/docs/system/task-scheduler.rst @@ -0,0 +1,60 @@ +.. _task-scheduler: + + +Task scheduler +-------------- + +| Task scheduler — allows scheduled task execution. Note that scripts excecuted this way are executed as root user - this may be dangerous. +| Together with :ref:`commandscripting` this can be used for automating configuration. + +.. code-block:: sh + + system + task-scheduler + task <name> + cron-spec <UNIX cron time spec> + executable + arguments <arguments string> + path <path to executable> + interval + <int32>[mhd] + +Interval +******** + +You are able to set the time as an time interval. + +.. code-block:: sh + + set system task-scheduler task <name> interval <value><suffix> + +Sets the task to execute every N minutes, hours, or days. Suffixes: + + * m — minutes + * h — hours + * d — days + +If suffix is omitted, minutes are implied. + +Or set the execution time in common cron time. + +.. code-block:: sh + + set system task-scheduler task TEST crontab-spec "* * * 1 *" + +Example +******* + +.. code-block:: sh + + system + task-scheduler + task mytask + interval 2h + executable + path /config/scripts/mytask + arguments "arg1 arg2 arg3" + task anothertask + cron-spec "* * * 1 *" + executable + path /config/scripts/anothertask
\ No newline at end of file diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 71345074..04cb9d80 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -85,8 +85,11 @@ Several options are available for changing the display output. Press `h` to invoke the built in help system. To quit, just press `q` and you'll be returned to the VyOS command prompt. -Monitoring Network Interfaces ------------------------------ +Monitoring +---------- + +Network Interfaces +^^^^^^^^^^^^^^^^^^ It's possible to monitor network traffic, either at the flow level or protocol level. This can be useful when troubleshooting a variety of protocols and @@ -161,6 +164,141 @@ The `unlimited` keyword is used to specify that an unlimited number of packets can be captured (by default, 1,000 packets are captured and you're returned to the VyOS command prompt). +Interface Bandwith +^^^^^^^^^^^^^^^^^^ + +to take a quick view on the used bandwith of an interface use the ``monitor bandwith`` command + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth interface eth0 + +show the following: + +.. code-block:: sh + + eth0 bmon 3.5 + Interfaces │ RX bps pps %│ TX bps pps % + >eth0 │ 141B 2 │ 272B 1 + ───────────────────────────────┴───────────────────────┴──────────────────────────────────────────────────────────────── + B (RX Bytes/second) + 198.00 .|....|..................................................... + 165.00 .|....|..................................................... + 132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + ───────────────────────────────────────── Press d to enable detailed statistics ──────────────────────────────────────── + ─────────────────────────────────────── Press i to enable additional information ─────────────────────────────────────── + Wed Apr 3 14:46:59 2019 Press ? for help + +| Press ``d`` for more detailed informations or ``i`` for additional information. +| To exit press ``q`` and than ``y`` + +Interface performance +^^^^^^^^^^^^^^^^^^^^^ + +To take a look on the network bandwith between two nodes, the ``monitor bandwidth-test`` command is used to run iperf. + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth-test + Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test + +| The ``accept`` command open a listen iperf server on TCP Port 5001 +| The ``initiate`` command conncet to this server. + +.. code-block:: sh + + vyos@vyos:~$ monitor bandwidth-test initiate + Possible completions: + <hostname> Initiate a bandwidth test to specified host (port TCP/5001) + <x.x.x.x> + <h:h:h:h:h:h:h:h> + + +Monitor command +^^^^^^^^^^^^^^^ + +The ``monitor command`` command allows you to repeatedly run a command to view a continuously refreshed output. +The command is run and output every 2 seconds, allowing you to monitor the output continuously without having to re-run the command. This can be useful to follow routing adjacency formation. + +.. code-block:: sh + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every 2 seconds. + +.. code-block:: sh + + Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper s... Sun Mar 26 02:49:46 2019 + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.168.1.1/24 u/u + eth0.5 198.51.100.4/24 u/u WAN + lo 127.0.0.1/8 u/u + ::1/128 + vti0 172.32.254.2/30 u/u + vti1 172.32.254.9/30 u/u + +Clear Command +------------- + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the ``clear`` command in Operational mode. + +to clear the console output + +.. code-block:: sh + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: sh + + # clear all interfaces + vyos@vyos:~$ clear interface ethernet counters + # clear specific interface + vyos@vyos:~$ clear interface ehternet eth0 counters + +The command follow the same logic as the ``set`` command in configuration mode. + +.. code-block:: sh + + # clear all counters of a interface type + vyos@vyos:~$ clear interface <interface_type> counters + # clear counter of a interface in interface_type + vyos@vyos:~$ clear interface <interface_type> <interace_name> counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: sh + + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters + + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters + + + .. _mtr: http://www.bitwizard.nl/mtr/ .. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html .. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html |