diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 157 |
1 files changed, 89 insertions, 68 deletions
@@ -9,61 +9,77 @@ For VyOS 1.1.x, use the build-iso repository. # What is VyOS -VyOS is an open source operating system for network devices (routers, firewalls and so on). -If you want to use it in your network, check out download and installation instructions at https://vyos.io +VyOS is an open source operating system for network devices (routers, firewalls +and so on). If you want to use it in your network, check out download and +installation instructions at https://vyos.io If you want to modify VyOS and/or join its development, read on. -VyOS is not new. It is a fork of Vyatta Core that was created when the open source version of it was -discontinued. If you are a Vyatta Core user, you can upgrade your installation to VyOS. +VyOS is not new. It is a fork of Vyatta Core that was created when the open +source version of it was discontinued. If you are a Vyatta Core user, you can +upgrade your installation to VyOS. # What is this repository? -VyOS is a GNU/Linux distribution based on Debian. Just like any other distribution, it consists of multiple -packages. +VyOS is a GNU/Linux distribution based on Debian. Just like any other +distribution, it consists of multiple packages. -Some packages are taken from the upstream, while other are modified or written from scratch by VyOS developers. -Every package maintained by the VyOS team has its own git repository. VyOS image build is therefore a multi-step -process. Packages are compiled first, then an ISO is built from Debian packages and our own packages. +Some packages are taken from the upstream, while other are modified or written +from scratch by VyOS developers. Every package maintained by the VyOS team has +its own git repository. VyOS image build is therefore a multi-step process. +Packages are compiled first, then an ISO is built from Debian packages and our +own packages. -This is the top level repository that contains links to repositories with VyOS-specific packages (organized -as git submodules) and scripts and data that are used for building those packages and the installation image. +This is the top level repository that contains links to repositories with VyOS +specific packages (organized as Git submodules) and scripts and data that are +used for building those packages and the installation image. # Structure of this repository There are several directories with their own purpose: - build/ Used for temporary files used for the build and for build artifacts - scripts/ Contains scripts that are used for the build process - data/ Contains data required for buildng the ISO (such as boot splash) - tools/ Contains scripts that are used for maintainer's tasks automation - and other purposes, but not in ISO build process + build/ Used for temporary files used for the build and for build artifacts + scripts/ Scripts that are used for the build process + data/ Data required for buildng the ISO (such as boot splash) + tools/ Scripts that are used for maintainer's tasks automation and other + purposes, but not during ISO build process # Building VyOS installation images ## Prerequisites -To build a VyOS image, you need Debian 8 "Jessie" environment (with jessie-backports repository). -You can create it with [debootstrap](https://wiki.debian.org/Debootstrap) on Debian, Ubuntu and many other distributions. -To create a Debian 8 "Jessie" environment under vyos-chroot directory, run these commands: +To build a VyOS image, you need Debian 8 "Jessie" environment (with +jessie-backports repository). You can create it with +[debootstrap](https://wiki.debian.org/Debootstrap) on Debian, Ubuntu and many +other distributions. To create a Debian 8 "Jessie" environment under vyos-chroot +directory, run these commands: -``` -$ sudo apt-get install debootstrap # (Note: This is on Debian/Ubuntu, adjust it for your favorite distro package manager) +Note: This is on Debian/Ubuntu, adjust it for your favorite distro package manager! + +```bash +$ sudo apt-get install debootstrap $ sudo debootstrap jessie vyos-chroot $ sudo chroot vyos-chroot -# echo "deb http://deb.debian.org/debian jessie-backports main" >> /etc/apt/sources.list -# apt-get update +$ echo "deb http://deb.debian.org/debian jessie-backports main" >> /etc/apt/sources.list +$ apt-get update ``` -Several packages are required for building the ISO: python3, live-build, pbuilder, python3-pystache. The ./configure script -will warn you if any dependencies are missing. -Individual packages may have other build dependencies. If some dependencies are missing, package build scripts will tell you. +Several packages are required for building the ISO: +* `python3` +* `live-build` +* `pbuilder` +* `python3-pystache` + +The `./configure` script will warn you if any dependencies are missing. Individual +packages may have other build dependencies. If some dependencies are missing, +package build scripts will tell you. ## Building the ISO image inside a docker container -Using Dockerfile you can create your own docker container that can be used to build a VyOS ISO image. -The Dockerfile contains some of the most used packages needed for a VyOS build ISO process. +Using our `Dockerfile` you can create your own Docker container that can be used +to build a VyOS ISO image. The `Dockerfile` contains some of the most used +packages needed for a VyOS build ISO process. ``` squashfs-tools # Required for squashfs file system @@ -78,8 +94,8 @@ lsb-release # Required, used by configure script fakechroot # Required, for ISO build devscripts # Optional, for building submodules (kernel etc) kernel-package # Optional, for building the kernel -libtool # Optional, for building certain packages (eg vyatta-op-vpn) -libglib2.0-dev # Optional, for building vyatta-cfg +libtool # Optional, for building certain packages (vyatta-op-vpn) +libglib2.0-dev # Optional, for building vyatta-cfg libboost-filesystem-dev # Optional, for building vyatta-cfg libapt-pkg-dev # Optional, for building vyatta-cfg flex # Optional, for building vyatta-cfg @@ -90,75 +106,80 @@ vim # Optional, vim, vi, nano or other text editor ``` To build the docker image: - ``` docker build -t vyos-builder $PATH_TO_Dockerfile ``` To run the docker image: - ``` docker run --privileged -v /HOST_PATH/images:/vyos --name=vyos_node_builder -d vyos-builder bash ``` -* docker container must be run with --privileged flag -* is recommended to run the container with a volume mapped in order to easy export built VyOS ISO images -to the "external" world + +NOTE: + +* Docker container must be run with `--privileged` flag +* We recommended to run the container with a volume mapped in order to easy + export built VyOS ISO images to the "external" world To connect to the docker image once is running: ``` docker exec -it vyos_node_builder bash ``` -After the docker container is running you can git clone the vyos-build repository inside the container -and follow up the bellow instructions in order to build the VyOS ISO image +After the docker container is running you can git clone the vyos-build repository +inside the container and follow up the bellow instructions in order to build the +VyOS ISO image ## Building the ISO image -Before you can build an image, you need to configure your build. +Before you can build an image, you need to configure your build. To build an image, use the following commands: - -``` -./configure -make iso +```bash +$ ./configure +$ make iso ``` -The ./configure script has a number of options that you can see by calling it with --help +The `./configure` script has a number of options that you can see by calling it +with `--help` ## Building the images for virtualization platforms * QEMU - Run following command after building the ISO image. - -``` -make qemu +```bash +$ make qemu ``` * VMware - Run following command after building the QEMU image. - -``` -make vmware +```bash +$ make vmware ``` # Development process -## git branches - -The default branch that contains the most recent VyOS code is called 'current' rather than 'master'. -We know if'ts confusing, but it's not easy to fix. -In a nutshell, the code we inherited from Vyatta Core had its master branch so out of sync with everything -it was beyong any repair. Vyatta developers used to create a new branch not when a release is ready for -code freeze, but rather before starting to work on a new release. -This is hard to change in existing code, so this is just the way it is, for now. - -All new code goes to the 'current' branch. When it's time for a code freeze, a new branch is created -for the release, and new code from 'current' is backported to the release branch as needed. - -In packages that originate from VyOS the master branch is kept in sync with "current", but we still use -"current" as default branch for uniformity. When the last legacy package is gone, we will switch to using -the master branch and retire "current". - -For branch naming we use chemical elements (hydrogen, helium, ...). +## Git branches + +The default branch that contains the most recent VyOS code is called `current` +rather than `master`. We know it's confusing, but it's not easy to fix. In a +nutshell, the code we inherited from Vyatta Core had its `master` branch so out +of sync with everything it was beyong any repair. Vyatta developers used to create +a new branch not when a release is ready for code freeze, but rather before +starting to work on a new release. This is hard to change in existing code, so +this is just the way it is, for now. + +All new code goes to the `current` branch. When it's time for a code freeze, a +new branch is created for the release, and new code from `current` is backported +to the release branch as needed. + +In packages that originate from VyOS the master branch is kept in sync with +`current`, but we still use `current` as default branch for uniformity. When the +last legacy package is gone, we will switch to using the `master` branch and +retire `current`. + +For branch naming we use chemical elements: +* hydrogen +* helium +* lithium +* ... |