From 6d3fcf76bf829306bc812ba18eef186d8d165f66 Mon Sep 17 00:00:00 2001 From: Daniil Baturin <daniil@baturin.org> Date: Sun, 20 Dec 2015 05:04:12 -0500 Subject: Master branch README. --- README.md | 56 +++++--------------------------------------------------- 1 file changed, 5 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 406e9ac0..84a277a4 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,9 @@ VyOS toplevel build =================== -# WARNING +For historical reasons, VyOS uses branch other than master as default branch. +We know it's confusing and it's against any accepted practice, but this is the way it is, +at least until nextgen VyOS is ready. -This is repository is for the ongoing work on porting VyOS to Debian Jessie. It is not yet ready to use. -For building stable release images, refer to the vyos/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 http://vyos.net - -If you want to modify VyOS and/or join its development, read on. - -# What is this repository? - -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. - -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 - -# Building VyOS installation images - -## Prerequisites - -To build a VyOS image, you need a machine that runs Debian Jessie. Other build hosts are not supported. - -Several packages are required for building the ISO and all packages, namely live-build, pbuilder, and dev-scripts. -Individual packages may have other build dependencies. If some packages are missing, build scripts will tell you. - -## Building the ISO image - -Before you can build an image, you need to configure your build. - -To build an image, use the following commands: - ./configure - make iso - -The ./configure script has a number of options that you can see by calling it with --help +The branch that contains the most recent development version is called 'current'. Please refer to it +isntead of the master branch. -- cgit v1.2.3 From 2268a65ba8edf92400ea185a36e784365de2e853 Mon Sep 17 00:00:00 2001 From: Daniil Baturin <daniil@baturin.org> Date: Sat, 23 Jun 2018 04:37:31 +0200 Subject: Revert "Master branch README." This reverts commit 6d3fcf76bf829306bc812ba18eef186d8d165f66. --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 84a277a4..406e9ac0 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,55 @@ VyOS toplevel build =================== -For historical reasons, VyOS uses branch other than master as default branch. -We know it's confusing and it's against any accepted practice, but this is the way it is, -at least until nextgen VyOS is ready. +# WARNING -The branch that contains the most recent development version is called 'current'. Please refer to it -isntead of the master branch. +This is repository is for the ongoing work on porting VyOS to Debian Jessie. It is not yet ready to use. +For building stable release images, refer to the vyos/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 http://vyos.net + +If you want to modify VyOS and/or join its development, read on. + +# What is this repository? + +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. + +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 + +# Building VyOS installation images + +## Prerequisites + +To build a VyOS image, you need a machine that runs Debian Jessie. Other build hosts are not supported. + +Several packages are required for building the ISO and all packages, namely live-build, pbuilder, and dev-scripts. +Individual packages may have other build dependencies. If some packages are missing, build scripts will tell you. + +## Building the ISO image + +Before you can build an image, you need to configure your build. + +To build an image, use the following commands: + ./configure + make iso + +The ./configure script has a number of options that you can see by calling it with --help -- cgit v1.2.3 From 24e264fd1862d2397e307928e91619fe6158fb04 Mon Sep 17 00:00:00 2001 From: Daniil Baturin <daniil@baturin.org> Date: Sat, 23 Jun 2018 04:38:49 +0200 Subject: Break overly long lines. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c6c0f1e..140a3b28 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,9 @@ There are several directories with their own purpose: ## 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) -- cgit v1.2.3 From ac376a53605ea13502ed432206d7a0929f954b4a Mon Sep 17 00:00:00 2001 From: Christian Poessinger <christian@poessinger.com> Date: Sat, 23 Jun 2018 16:30:58 +0200 Subject: README.md: use live-build instead of live-helper ... as suggested by @hagbard-01 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 140a3b28..b124a5b1 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ squashfs-tools # Required for squashfs file system git # Required, for cloning the source autoconf # Required, for generating build scripts dpkg-dev # Required, used in build scripts -live-helper # Required, for ISO build +live-build # Required, for ISO build syslinux # Required, for ISO build genisoimage # Required, for ISO build make # Required, for ISO build -- cgit v1.2.3 From 9e3d312972b2edfa1e2199f78421b1f142f1d2d1 Mon Sep 17 00:00:00 2001 From: Christian Poessinger <christian@poessinger.com> Date: Sun, 24 Jun 2018 12:07:11 +0200 Subject: README.md: make it look more fancy --- README.md | 157 +++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 89 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index b124a5b1..d2bacf9a 100644 --- a/README.md +++ b/README.md @@ -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 +* ... -- cgit v1.2.3 From a6500e0084f9f94202550edad8cb605952c549be Mon Sep 17 00:00:00 2001 From: Christian Poessinger <christian@poessinger.com> Date: Sun, 24 Jun 2018 12:19:12 +0200 Subject: README.md: place QEMU and VMWare in dedicated chapter --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d2bacf9a..51d0ee9a 100644 --- a/README.md +++ b/README.md @@ -145,13 +145,15 @@ with `--help` ## Building the images for virtualization platforms -* QEMU +### QEMU + Run following command after building the ISO image. ```bash $ make qemu ``` -* VMware +### VMware + Run following command after building the QEMU image. ```bash $ make vmware -- cgit v1.2.3