diff options
| -rw-r--r-- | docs/configuration-overview.rst | 47 | ||||
| -rw-r--r-- | docs/contributing/build-vyos.rst | 335 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 20 | ||||
| -rw-r--r-- | docs/contributing/upstream-packages.rst | 72 | ||||
| -rw-r--r-- | docs/install.rst | 70 | ||||
| -rw-r--r-- | docs/interfaces/pppoe.rst | 2 | ||||
| -rw-r--r-- | docs/interfaces/wirelessmodem.rst | 4 | ||||
| -rw-r--r-- | docs/quick-start.rst | 52 | ||||
| -rw-r--r-- | docs/vpn/sstp.rst | 42 |
9 files changed, 490 insertions, 154 deletions
diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index bf9c57d9..71bfc360 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -299,11 +299,14 @@ different levels in the hierarchy. Warning: configuration changes have not been saved. vyos@vyos:~$ +.. _save: + .. cfgcmd:: save - In order to preserve configuration changes upon reboot, the - configuration must also be saved once applied. This is done using the - :cfgcmd:`save` command in configuration mode. + Use this command to preserve configuration changes upon reboot. By + default it is stored at */config/config.boot*. In the case you want + to store the configuration file somewhere else, you can add a local + path, an SCP address, an FTP address or a TFTP address. .. code-block:: none @@ -619,14 +622,11 @@ By default the difference with the running config is shown. This means four commits ago we did ``set system ipv6 disable-forwarding``. - - - Rollback Changes ---------------- You can rollback configuration changes using the rollback command. This -willn apply the selected revision and trigger a system reboot. +will apply the selected revision and trigger a system reboot. .. cfgcmd:: rollback <N> @@ -675,6 +675,39 @@ be ``config.boot-hostname.YYYYMMDD_HHMMSS``. vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts +Saving and loading manually +--------------------------- + +You can use the ``save`` and ``load`` commands if you want to manually +manage specific configuration files. + +When using the save_ command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the ``load`` command: + +.. cfgcmd:: load <URI> + + Use this command to load a configuration which will replace the + running configuration. Define the location of the configuration file + to be loaded. You can use a path to a local file, an SCP address, an + SFTP address, an FTP address, an HTTP address, an HTTPS address or a + TFTP address. + + .. code-block:: none + + vyos@vyos# load + Possible completions: + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + + + Restore Default --------------- diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index e8bb9f37..c6098763 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -257,6 +257,341 @@ The full and current list can be generated with ``./configure --help``: .. _build_custom_packages: +Linux Kernel +============ + +The Linux Kernel used by VyOS is heavily tied to the ISO build process. The +file ``data/defaults.json`` hosts a JSON definition if the Kernel version used +``kernel_version`` and the ``kernel_flavor`` of the Kernel which represents the +Kernels LOCAL_VERSION. Both together form the Kernel Version variable in the +system: + +.. code-block:: none + + vyos@vyos:~$ uname -r + 4.19.146-amd64-vyos + +Other packages (e.g. vyos-1x) add dependencies to the ISO build procedure on +e.g. the wireguard-modules package which itself adds a dependency on the Kernel +version used due to the module it ships. This may change (for WireGuard) in +future Kernel releases but as long as we have out-of-tree modules. + +* WireGuard +* Accel-PPP +* Intel NIC drivers +* Inter QAT + +Each of those modules holds a dependency on the Kernel Version and if you are +lucky enough to receive an ISO build error which sounds like: + +.. code-block:: none + + I: Create initramfs if it does not exist. + Extra argument '4.19.146-amd64-vyos' + Usage: update-initramfs {-c|-d|-u} [-k version] [-v] [-b directory] + Options: + -k version Specify kernel version or 'all' + -c Create a new initramfs + -u Update an existing initramfs + -d Remove an existing initramfs + -b directory Set alternate boot directory + -v Be verbose + See update-initramfs(8) for further details. + E: config/hooks/live/17-gen_initramfs.chroot failed (exit non-zero). You should check for errors. + +The most obvious reasons could be: + +* ``vyos-build`` repo is outdate, please ``git pull`` to update to the latest + release Kernel version from us. + +* You have your own custom Kernel `*.deb` packages in the `packages` folder but + missed to create all required out-of tree modules like Accel-PPP, WireGuard, + Intel QAT, Intel NIC + +Building The Kernel +------------------- + +The Kernel build is quiet easy, most of the required steps can be found in the +``vyos-build/packages/linux-kernel/Jenkinsfile`` but we will walk you through +it. + +Clone the Kernel source to `vyos-build/packages/linux-kernel/`: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel/ + $ git clone https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git + +Checkout the required Kernel version - see ``vyos-build/data/defaults.json`` +file (example uses kernel 4.19.146): + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel/linux + $ git checkout v4.19.146 + Checking out files: 100% (61536/61536), done. + Note: checking out 'v4.19.146'. + + You are in 'detached HEAD' state. You can look around, make experimental + changes and commit them, and you can discard any commits you make in this + state without impacting any branches by performing another checkout. + + If you want to create a new branch to retain commits you create, you may + do so (now or later) by using -b with the checkout command again. Example: + + git checkout -b <new-branch-name> + + HEAD is now at 015e94d0e37b Linux 4.19.146 + +Now we can use the helper script ``build-kernel.sh`` which does all the necessary +Voodoo by applying required patches from the `vyos-build/packages/linux-kernel/ +patches` folder, copying our Kernel configuration ``x86_64_vyos_defconfig`` to +the right location, and finally building the Debian packages. + +.. note:: Building the kernel will take some time depending on the speed and quantity of your CPU/cores and disk speed. Plan on 20 minutes or even longer on lower end harder + +.. code-block:: none + + (18:59) vyos_bld 412374ca36b8:/vyos/vyos-build/packages/linux-kernel [current] # ./build-kernel.sh + I: Copy Kernel config (x86_64_vyos_defconfig) to Kernel Source + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0001-VyOS-Add-linkstate-IP-device-attribute.patch + patching file Documentation/networking/ip-sysctl.txt + patching file include/linux/inetdevice.h + patching file include/linux/ipv6.h + patching file include/uapi/linux/ip.h + patching file include/uapi/linux/ipv6.h + patching file net/ipv4/devinet.c + Hunk #1 succeeded at 2319 (offset 1 line). + patching file net/ipv6/addrconf.c + patching file net/ipv6/route.c + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0002-VyOS-add-inotify-support-for-stackable-filesystems-o.patch + patching file fs/notify/inotify/Kconfig + patching file fs/notify/inotify/inotify_user.c + patching file fs/overlayfs/super.c + Hunk #2 succeeded at 1713 (offset 9 lines). + Hunk #3 succeeded at 1739 (offset 9 lines). + Hunk #4 succeeded at 1762 (offset 9 lines). + patching file include/linux/inotify.h + I: Apply Kernel patch: /vyos/vyos-build/packages/linux-kernel/patches/kernel/0003-RFC-builddeb-add-linux-tools-package-with-perf.patch + patching file scripts/package/builddeb + I: make x86_64_vyos_defconfig + HOSTCC scripts/basic/fixdep + HOSTCC scripts/kconfig/conf.o + YACC scripts/kconfig/zconf.tab.c + LEX scripts/kconfig/zconf.lex.c + HOSTCC scripts/kconfig/zconf.tab.o + HOSTLD scripts/kconfig/conf + # + # configuration written to .config + # + I: Generate environment file containing Kernel variable + I: Build Debian Kernel package + UPD include/config/kernel.release + /bin/sh ./scripts/package/mkdebian + dpkg-buildpackage -r"fakeroot -u" -a$(cat debian/arch) -b -nc -uc + dpkg-buildpackage: info: source package linux-4.19.146-amd64-vyos + dpkg-buildpackage: info: source version 4.19.146-1 + dpkg-buildpackage: info: source distribution buster + dpkg-buildpackage: info: source changed by vyos_bld <christian@poessinger.com> + dpkg-buildpackage: info: host architecture amd64 + dpkg-buildpackage: warning: debian/rules is not executable; fixing that + dpkg-source --before-build . + debian/rules build + make KERNELRELEASE=4.19.146-amd64-vyos ARCH=x86 KBUILD_BUILD_VERSION=1 KBUILD_SRC= + SYSTBL arch/x86/include/generated/asm/syscalls_32.h + + ... + + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: binaries to analyze should already be installed in their package's directory + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypto.so.1.1 (they use none of the library's symbols) + dpkg-shlibdeps: warning: package could avoid a useless dependency if /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/trace /vyos/vyos-build/packages/linux-kernel/linux/debian/toolstmp/usr/bin/perf were not linked against libcrypt.so.1 (they use none of the library's symbols) + dpkg-deb: building package 'linux-tools-4.19.146-amd64-vyos' in '../linux-tools-4.19.146-amd64-vyos_4.19.146-1_amd64.deb'. + dpkg-genbuildinfo --build=binary + dpkg-genchanges --build=binary >../linux-4.19.146-amd64-vyos_4.19.146-1_amd64.changes + dpkg-genchanges: warning: package linux-image-4.19.146-amd64-vyos-dbg in control file but not in files list + dpkg-genchanges: info: binary-only upload (no source code included) + dpkg-source --after-build . + dpkg-buildpackage: info: binary-only upload (no source included) + + +In the end you will be presented with the Kernel binary packages which you can +then use in your custom ISO build process, by placing all the `*.deb` files in +the vyos-build/packages folder where they will be used automatically when building VyOS as documented above. + +Building Out-Of-Tree Modules +---------------------------- + +Building the Kernel is one part, but now you also need to build the required +out-of-tree modules so everything is lined up and the ABIs match. To do so, +you can again take a look at ``vyos-build/packages/linux-kernel/Jenkinsfile`` +to see all of the required modules and their selected version. We will show you +once how to build all the current required modules. + +WireGuard +^^^^^^^^^ + +First clone the source code and checkout the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://salsa.debian.org/debian/wireguard-linux-compat.git + $ cd wireguard-linux-compat + $ git checkout debian/1.0.20200712-1_bpo10+1 + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ ./build-wireguard-modules.sh + I: Apply WireGuard patch: /vyos/packages/linux-kernel/patches/wireguard-linux-compat/0001-Debian-build-wireguard-modules-package.patch + patching file debian/control + patching file debian/rules + I: Build Debian WireGuard package + dpkg-buildpackage: info: source package wireguard-linux-compat + dpkg-buildpackage: info: source version 1.0.20200712-1~bpo10+1 + dpkg-buildpackage: info: source distribution buster-backports + dpkg-buildpackage: info: source changed by Unit 193 <unit193@debian.org> + dpkg-buildpackage: info: host architecture amd64 + dpkg-source --before-build . + dpkg-source: info: using patch list from debian/patches/series + dpkg-source: info: applying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-source: info: applying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + + ... + + dpkg-genchanges: info: binary-only upload (no source code included) + debian/rules clean + dh clean + dh_clean + dpkg-source --after-build . + dpkg-source: info: unapplying 0002-Avoid-trying-to-compile-on-debian-5.5-kernels-Closes.patch + dpkg-source: info: unapplying 0001-Makefile-do-not-use-git-to-get-version-number.patch + dpkg-buildpackage: info: binary-only upload (no source included) + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Accel-PPP +^^^^^^^^^ + +First clone the source code and checkout the appropriate version by running: + +.. code-block:: none + + $ cd vyos-build/packages/linux-kernel + $ git clone https://github.com/accel-ppp/accel-ppp.git + +We again make use of a helper script and some patches to make the build work. +Just run the following command: + +.. code-block:: none + + $ ./build-accel-ppp.sh + I: Build Accel-PPP Debian package + CMake Deprecation Warning at CMakeLists.txt:3 (cmake_policy): + The OLD behavior for policy CMP0003 will be removed from a future version + of CMake. + + The cmake-policies(7) manual explains that the OLD behaviors of all + policies are deprecated and that a policy should be set to OLD only under + specific short-term circumstances. Projects should be ported to the NEW + behavior and not rely on setting a policy to OLD. + + -- The C compiler identification is GNU 8.3.0 + + ... + + CPack: Create package using DEB + CPack: Install projects + CPack: - Run preinstall target for: accel-ppp + CPack: - Install project: accel-ppp + CPack: Create package + CPack: - package: /vyos/vyos-build/packages/linux-kernel/accel-ppp/build/accel-ppp.deb generated. + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel NIC +^^^^^^^^^ + +The Intel NIC drivers do not come from a Git repository, instead we just fetch +the tarballs from our mirror and compile them. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + ./build-intel-drivers.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 490k 100 490k 0 0 648k 0 --:--:-- --:--:-- --:--:-- 648k + I: Compile Kernel module for Intel ixgbe driver + + ... + + I: Building Debian package vyos-intel-iavf + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-iavf_4.0.1-0_amd64.deb"} + I: Cleanup iavf source + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + +Intel QAT +^^^^^^^^^ +The Intel QAT (Quick Assist Technology) drivers do not come from a Git +repository, instead we just fetch the tarballs from 01.org, Intels Open-Source +website. + +Simply use our wrapper script to build all of the driver modules. + +.. code-block:: none + + $ ./build-intel-qat.sh + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 5065k 100 5065k 0 0 1157k 0 0:00:04 0:00:04 --:--:-- 1157k + I: Compile Kernel module for Intel qat driver + checking for a BSD-compatible install... /usr/bin/install -c + checking whether build environment is sane... yes + checking for a thread-safe mkdir -p... /bin/mkdir -p + checking for gawk... gawk + checking whether make sets $(MAKE)... yes + + ... + + I: Building Debian package vyos-intel-qat + Doing `require 'backports'` is deprecated and will not load any backport in the next major release. + Require just the needed backports instead, or 'backports/latest'. + Debian packaging tools generally labels all files in /etc as config files, as mandated by policy, so fpm defaults to this behavior for deb packages. You can disable this default behavior with --deb-no-default-config-files flag {:level=>:warn} + Created package {:path=>"vyos-intel-qat_1.7.l.4.9.0-00008-0_amd64.deb"} + I: Cleanup qat source + + +After compiling the packages you will find yourself the newly generated `*.deb` +binaries in ``vyos-build/packages/linux-kernel`` from which you can copy them +to the ``vyos-build/packages`` folder for inclusion during the ISO build. + + Packages ======== diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 17f5cc48..86371845 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -271,7 +271,7 @@ device if you happen to be a crazy scientist. #!/usr/bin/env python3 # - # Copyright (C) 2019 VyOS maintainers and contributors + # Copyright (C) 2020 VyOS maintainers and contributors # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License version 2 or later as @@ -291,10 +291,16 @@ device if you happen to be a crazy scientist. from vyos import ConfigError def get_config(): - vc = Config() + if config: + conf = config + else: + conf = Config() + + # Base path to CLI nodes + base = ['...', '...'] # Convert the VyOS config to an abstract internal representation - config = ... - return config + config_data = conf.get_config_dict(base, key_mangling=('-', '_'), get_first_key=True) + return config_data def verify(config): # Verify that configuration is valid @@ -311,8 +317,10 @@ device if you happen to be a crazy scientist. pass try: - config = get_config() - verify(config) + c = get_config() + verify(c) + generate(c) + apply(c) except ConfigError as e: print(e) sys.exit(1) diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index d43e61f3..5c48bbb3 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -59,26 +59,6 @@ reason we debianize that module by hand now, using this procedure: The package ends up in deb_dist dir. -ppp -^^^ - -Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and -non-informative pppX requires a patch that is neither in the upstream nor in -Debian. - -We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian - -The patches for pre-up renaming are: - -* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae -* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9 - -Additionally, there's a patch for reopening the log file to better support -logging to files, even though it's less essential: -https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f - -The patches were written by Stephen Hemminger back in the Vyatta times. - mdns-repeater ^^^^^^^^^^^^^ @@ -95,58 +75,6 @@ https://github.com/vyos/udp-broadcast-relay No special build procedure is required. -Linux kernel -^^^^^^^^^^^^ - -In the past a fork of the Kernel source code was kept at the well-known -location of https://github.com/vyos/vyos-kernel - where it is kept for history. - -Nowadays the Kernel we use is the upstream source code which is patched -with two additional patches from the good old Vyatta times which never made it -into the mainstream Kernel. The patches can be found here: -https://github.com/vyos/vyos-build-kernel/tree/master/patches/kernel and are -automatically applied to the Kernel by the Jenkins Pipeline which is used to -generate the Kernel binaries. - -The Pipeline script not only builds the Kernel with the configuration named -``x86_64_vyos_defconfig`` which is located in the vyos-build-kernel repository, -too - but in addition also builds some Intel out-of-tree drivers, WireGuard -(as long it is not upstreamed) and Accel-PPP. - -The ``Jenkinsfile`` tries to be as verbose as possible on each individual build -step. - -Linux Firmware -^^^^^^^^^^^^^^ - -More and more hardware cards require an additional firmware which is not open -source. The Kernel community hosts a special linux-firmware Git repository -with all available binary files which can be loaded by the Kernel. - -The ``vyos-build`` repository fetches a specific commit of the linux-firmware -repository and embeds those binaries into the resulting ISO image. This step is -done in the ``data/live-build-config/hooks/live/40-linux-firmware.chroot`` file. - -If the firmware needs to be updated it is sufficient to just exchange the Git -commit id we reference in our build. - -Intel NIC drivers -^^^^^^^^^^^^^^^^^ - -We do not make use of the building Intel NIC drivers except for e1000e. Main -reason is that the out of tree Intel drivers seem be perform a bit better, -e.q. have proper receive-side-scaling and multi-queue support. - -Drivers are build as part of the Kernel Pipeline - read above. - -Accel-PPP -^^^^^^^^^ - -Accel-PPP used to be an upstream fork for quite some time but now has been -converted to make use of the upstream source code and build system. - -It is build as part of the Kernel Pipeline - read above. - hvinfo ^^^^^^ diff --git a/docs/install.rst b/docs/install.rst index a210c1ad..11d0fc88 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -351,7 +351,7 @@ installation method which allows deploying VyOS through the network. * :ref:`tftp-server` * Webserver (HTTP) - optional, but we will use it to speed up installation * VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files ``pxelinux.0`` and ``ldlinux.c32`` `from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution <https://kernel.org/pub/linux/utils/boot/syslinux/>`_ Configuration ------------- @@ -363,7 +363,7 @@ Configure a DHCP server to provide the client with: * An IP address * The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is ``pxelinux.0`` +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* In this example we configured an existent VyOS as the DHCP server: @@ -389,17 +389,18 @@ Step 2: TFTP Configure a TFTP server so that it serves the following: -* The ``pxelinux.0`` file from the Syslinux distribution -* The ``ldlinux.c32`` file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the ``vmlinuz`` - file inside the ``/live`` directory of the extracted contents from the ISO - file +* The *pxelinux.0* file from the Syslinux distribution +* The *ldlinux.c32* file from the Syslinux distribution +* The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. * The initial ramdisk of the VyOS ISO you want to deploy. That is the - ``initrd.img`` file inside the ``/live`` directory of the extracted contents - from the ISO file. Do not use an empty (0 bytes) initrd.img file you might - find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration file. - We will use the configuration_ file shown below, which we named default_. + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +* A directory named pxelinux.cfg which must contain the configuration + file. We will use the configuration_ file shown below, which we named + default_. .. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config .. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration @@ -446,35 +447,44 @@ Example of simple (no menu) configuration file: Step 3: HTTP ^^^^^^^^^^^^ -As you can read in the configuration file, we are sending ``filesystem.squashfs`` -through HTTP. As that is a heavy file, we choose HTTP to speed up the transfer -over TFTP. +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. -First run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the ``filesystem.squashfs`` -file. The file can be found inside the ``/live`` directory of the extracted -contents of the ISO file. +**First** run a web server - you can use a simple one like +`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. -Second, edit the configuration file of the :ref:`install_from_tftp` so that it shows -the correct URL at ``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http://<address_of_your_HTTP_server>/filesystem.squashfs``. -And third, restart the TFTP service. If you are using VyOS as your TFTP Server, you can restart -the service with ``sudo service tftpd-hpa restart``. +.. note:: Do not change the name of the *filesystem.squashfs* file. If + you are working with different versions, you can create different + directories instead. -.. note:: Make sure the available directories and files in both TFTP and HTTP - server have the right permissions to be accessed from the booting clients. +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +``sudo service tftpd-hpa restart``. + +.. note:: Make sure the available directories and files in both TFTP + and HTTP server have the right permissions to be accessed from the + booting clients. .. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html Client Boot ----------- -Finally, turn on your PXE-enabled client or clients. They will automatically get an IP -address from the DHCP server and start booting into VyOS live from the files -automatically taken from the TFTP and HTTP servers. +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. -Once finished you will be able to proceed with the ``install image`` command as -in a regular VyOS installation. +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index ae6b11cc..75fe0a40 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -79,7 +79,7 @@ Configuration .. cfgcmd:: set interfaces pppoe <interface> connect-on-demand - Enables or disables on-demand PPPoE connection on a PPPoE unit. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPPoE connections automatically once traffic passes through the interface. A disabled on-demand diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst index 5cded6c5..c41e71bf 100644 --- a/docs/interfaces/wirelessmodem.rst +++ b/docs/interfaces/wirelessmodem.rst @@ -35,9 +35,9 @@ Address Do not install DNS nameservers received from ISP into system wide nameserver list. -.. cfgcmd:: set interfaces wirelessmodem <interface> ondemand +.. cfgcmd:: set interfaces wirelessmodem <interface> connect-on-demand - Enables or disables on-demand WWAN connection. + When set the interface is enabled for "dial-on-demand". Use this command to instruct the system to establish a PPP connection automatically once traffic passes through the interface. A disabled on-demand diff --git a/docs/quick-start.rst b/docs/quick-start.rst index 19ee9f6e..550bfd77 100644 --- a/docs/quick-start.rst +++ b/docs/quick-start.rst @@ -4,7 +4,7 @@ Quick Start ########### -This chapter will guide you on how to get up to speed using your new VyOS +This chapter will guide you on how to get up to speed quickly using your new VyOS system. It will show you a very basic configuration example that will provide a :ref:`nat` gateway for a device with two network interfaces (`eth0` and `eth1`). @@ -14,6 +14,10 @@ a :ref:`nat` gateway for a device with two network interfaces (`eth0` and Configuration Mode ################## +By default, VyOS is in operational mode, and the command prompt displays a `$`. To configure VyOS, +you will need to enter configuration mode, resulting in the command prompt displaying a `#`, as +demonstrated below: + .. code-block:: none vyos@vyos$ configure @@ -22,13 +26,13 @@ Configuration Mode Commit and Save ################ -After every configuration change you need to apply the changes by using the +After every configuration change, you need to apply the changes by using the following command: .. code-block:: none commit -Once your configuration works as expected you can save it permanently. +Once your configuration works as expected, you can save it permanently by using the following command: .. code-block:: none @@ -37,9 +41,9 @@ Once your configuration works as expected you can save it permanently. Interface Configuration ####################### -* Your outside/WAN interface will be `eth0`, it receives it's interface address - be means of DHCP. -* Your internal/LAN interface is `eth1`. It uses a fixed IP address of +* Your outside/WAN interface will be `eth0`. It will receive its interface address + via DHCP. +* Your internal/LAN interface will be `eth1`. It will use a static IP address of `192.168.0.1/24`. After switching to :ref:`quick-start-configuration-mode` issue the following @@ -69,14 +73,17 @@ on specific addresses only. Configure DHCP/DNS Servers ########################## -* Provide DHCP service on your internal/LAN network where VyOS will act - as the default gateway and DNS server. -* Client IP addresses are assigned from the range ``192.168.0.9 - - 192.168.0.254`` +The following settings will configure DHCP and DNS services on your internal/LAN network, +where VyOS will act as the default gateway and DNS server. + +* The default gateway and DNS recursor address will be `192.168.0.1/24` +* The address range `192.168.0.2/24 - 192.168.0.8/24` will be reserved for static assignments +* DHCP clients will be assigned IP addresses within the range of `192.168.0.9 - 192.168.0.254` + and have a domain name of `internal-network` * DHCP leases will hold for one day (86400 seconds) -* VyOS will server as full DNS recursor - no need to bother the Google or - Cloudflare DNS servers (good for privacy) -* Only clients from your internal/LAN network can use the DNS resolver +* VyOS will serve as a full DNS recursor, replacing the need to utilize Google, + Cloudflare, or other public DNS servers (which is good for privacy) +* Only hosts from your internal/LAN network can use the DNS recursor .. code-block:: none @@ -95,7 +102,8 @@ Configure DHCP/DNS Servers NAT ### -* Configure :ref:`source-nat` for our internal/LAN network +The following settings will configure :ref:`source-nat` rules for our internal/LAN network, allowing +hosts to communicate through the outside/WAN network via IP masquerade. .. code-block:: none @@ -188,11 +196,23 @@ Set up :ref:`ssh_key_based_authentication`: Finally, try and SSH into the VyOS install as your new user. Once you have confirmed that your new user can access your router without a password, delete -the original ``vyos`` user and probably disable password authentication for -:ref:`ssh` at all: +the original ``vyos`` user and completely disable password authentication for +:ref:`ssh`: .. code-block:: none delete system login user vyos set service ssh disable-password-authentication +As above, commit your changes, save the configuration, and exit configuration mode: + +.. code-block:: none + + vyos@vyos# commit + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + vyos@vyos# exit + vyos@vyos$ + +You now should have a simple yet secure and functioning router to experiment with further. Enjoy! diff --git a/docs/vpn/sstp.rst b/docs/vpn/sstp.rst index de13b5ae..e5567cb6 100644 --- a/docs/vpn/sstp.rst +++ b/docs/vpn/sstp.rst @@ -23,9 +23,11 @@ certificates as well as a private PKI is required. certificates are not stored in the ``/config`` directory they will not be migrated during a software update. +Certificates +============ -Self Signed CA and Certificates -=============================== +Self Signed CA +-------------- To generate the CA, the server private key and certificates the following commands can be used. @@ -98,18 +100,18 @@ Configuration * **local**: All authentication queries are handled locally. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings gateway-address <gateway> +.. cfgcmd:: set vpn sstp gateway-address <gateway> Specifies single `<gateway>` IP address to be used as local address of PPP interfaces. -.. cfgcmd:: set vpn sstp network-settings client-ip-settings subnet <subnet> +.. cfgcmd:: set vpn sstp client-ip-pool subnet <subnet> Use `<subnet>` as the IP pool for all connecting clients. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool prefix <address> mask <number-of-bits> +.. cfgcmd:: set vpn sstp client-ipv6-pool prefix <address> mask <number-of-bits> Use this comand to set the IPv6 address pool from which an SSTP client will get an IPv6 prefix of your defined length (mask) to terminate the @@ -117,7 +119,7 @@ Configuration bit long, the default value is 64. -.. cfgcmd:: set vpn sstp network-settings client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> +.. cfgcmd:: set vpn sstp client-ipv6-pool delegate <address> delegation-prefix <number-of-bits> Use this command to configure DHCPv6 Prefix Delegation (RFC3633) on SSTP. You will have to set your IPv6 pool and the length of the @@ -126,7 +128,7 @@ Configuration delegation prefix can be set from 32 to 64 bit long. -.. cfgcmd:: set vpn sstp network-settings name-server <address> +.. cfgcmd:: set vpn sstp name-server <address> Connected client should use `<address>` as their DNS server. This command accepts both IPv4 and IPv6 addresses. Up to two nameservers @@ -152,23 +154,23 @@ SSL Certificates PPP Settings ------------ -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-failure <number> +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-failure <number> Defines the maximum `<number>` of unanswered echo requests. Upon reaching the value `<number>`, the session will be reset. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-interval <interval> +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-interval <interval> If this option is specified and is greater than 0, then the PPP module will send LCP pings of the echo request every `<interval>` seconds. -.. cfgcmd:: set vpn sstp ppp-settings lcp-echo-timeout +.. cfgcmd:: set vpn sstp ppp-options lcp-echo-timeout Specifies timeout in seconds to wait for any peer activity. If this option specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" is not used. -.. cfgcmd:: set vpn sstp ppp-settings mppe <require | prefer | deny> +.. cfgcmd:: set vpn sstp ppp-options mppe <require | prefer | deny> Specifies :abbr:`MPPE (Microsoft Point-to-Point Encryption)` negotioation preference. @@ -269,15 +271,15 @@ Example .. code-block:: none - set vpn sstp authentication local-users username foo password 'bar' - set vpn sstp authentication mode 'local' - set vpn sstp network-settings client-ip-settings gateway-address '192.0.2.254' - set vpn sstp network-settings client-ip-settings subnet '192.0.2.0/25' - set vpn sstp network-settings name-server '10.0.0.1' - set vpn sstp network-settings name-server '10.0.0.2' - set vpn sstp ssl ca-cert-file '/config/auth/ca.crt' - set vpn sstp ssl cert-file '/config/auth/server.crt' - set vpn sstp ssl key-file '/config/auth/server.key' + set vpn sstp authentication local-users username vyos password vyos + set vpn sstp authentication mode local + set vpn sstp gateway-address 192.0.2.254 + set vpn sstp client-ip-pool subnet 192.0.2.0/25 + set vpn sstp name-server 10.0.0.1 + set vpn sstp name-server 10.0.0.2 + set vpn sstp ssl ca-cert-file /config/auth/ca.crt + set vpn sstp ssl cert-file /config/auth/server.crt + set vpn sstp ssl key-file /config/auth/server.key Testing SSTP ============ |