1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
.. _build:
Building VyOS
=============
There are different ways you can build VyOS.
Building using a :ref:`Docker<build docker>` container, although not the only way, is the
easiest way as all dependencies are managed for you. It also allows you to
build ARM images on a x86 host.
However, you can also set up your own build machine and :ref:`build from source<build source>`.
.. note:: Starting with VyOS 1.2 the release model of VyOS has changed.
VyOS is now **free as in speech, but not as in beer**. This means
that while VyOS is still an open source project, the release ISOs are no
longer free and can only be obtained via subscription, or by contributing
to the community.
The source code remains public and an ISO can be built
using the process outlined here.
.. _build docker:
Docker
------
This will guide you though the process of building a VyOS ISO using
Docker_. This process has been tested on clean installs of Debian
Jessie, Stretch, and Buster.
Installing Docker_ and prerequisites
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: none
$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg2 \
software-properties-common
$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] \
https://download.docker.com/linux/debian $(lsb_release -cs) stable"
$ sudo apt-get update
$ sudo apt-get install -y docker-ce
To be able to use Docker_, the current non-root user should be added to the
``docker`` group by calling: ``usermod -aG docker yourusername``
.. note:: It is recommended to use that non-root user for the remaining steps.
.. note:: The build process needs to be built on a local file system, building
on SMB or NFS shares will result in the container failing to build properly!
Build Docker Container
^^^^^^^^^^^^^^^^^^^^^^
The container can built by hand or by fetching the pre-built one from
DockerHub. Using the pre-built containers from the `VyOS DockerHub organisation`_
will ensure that the container is always up-to-date. A rebuild is triggered
once the container changes (please note this will take 2-3 hours after pushing
to the vyos-build repository).
.. note: If you are using the pre-built container, it will be automatically
downloaded from DockerHub if it is not found on your local machine when
you build the ISO.
To manually download the container, run:
.. code-block:: none
$ docker pull vyos/vyos-build:crux
The container can always be built directly from source:
.. code-block:: none
$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b master --single-branch https://github.com/vyos/vyos-build # For rolling release
$ cd vyos-build
$ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2
$ docker build -t vyos/vyos-build docker # For rolling release
.. Note: We require one container per build branch, this means that the used
container in ``crux`` and ``master`` can and will differ once VyOS makes the
move towards Debian (10) Buster.
Build ISO
^^^^^^^^^
If you have not build your own Docker image, you need to clone the repository to your local machine:
.. code-block:: none
$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For rolling release
Now a fresh build of the VyOS ISO can begin. Change directory to the ``vyos-build`` directory and run:
.. code-block:: none
$ cd vyos-build
$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos/vyos-build:crux bash
vyos_bld@d4220bb519a0:/vyos# ./configure --architecture amd64 \
--build-by "your@email.tld" \
--build-type release --version 1.2.0
vyos_bld@d4220bb519a0:/vyos# sudo make iso
The successfully built ISO should now be in the ``build/`` directory as
``live-image-[architecture].hybrid.iso``.
Good luck!
.. note: Make sure to choose the matching container for the version of VyOS
that is being built, ``vyos/vyos-build:crux`` for VyOS 1.2 (crux) and
``vyos/vyos-build`` for rolling release.
.. _build source:
From source
-----------
To build from source, you will need:
- Debian Buster for VyOS 1.2
- Debian Stretch for the rolling releases
To start, clone the repository to your local machine:
.. code-block:: none
$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For VyOS 1.2
$ git clone -b crux --single-branch https://github.com/vyos/vyos-build # For rolling release
For the packages required, you can refer to the ``docker/Dockerfile`` file
in the repository_. The ``./configure`` script will also warn you if any
dependencies are missing.
Once you have the required dependencies, you may configure the build by
running ``./configure`` with your options. For details, refer to
:ref:`Customizing the build<customize>`.
Once you have configured your build, build the ISO by running:
.. code-block:: none
$ sudo make iso
The successfully built ISO should now be in the ``build/`` directory as
``live-image-[architecture].hybrid.iso``.
.. _customize:
Customizing the build
---------------------
The build can be customized with the following list of configure options.
The full and current list can be generated with ``./configure --help``:
.. code-block:: none
-h, --help show this help message and exit
--architecture ARCHITECTURE
Image target architecture (amd64 or i586 or armhf)
--build-by BUILD_BY Builder identifier (e.g. jrandomhacker@example.net)
--custom-package CUSTOM_PACKAGES
Custom packages to install from repositories
--build-type BUILD_TYPE
Build type, release or development
--debian-security-mirror DEBIAN_SECURITY_MIRROR
Debian security updated mirror
--version VERSION Version number (release builds only)
--debian-mirror DEBIAN_MIRROR
Debian repository mirror for ISO build
--vyos-mirror VYOS_MIRROR
VyOS package mirror
--pbuilder-debian-mirror PBUILDER_DEBIAN_MIRROR
Debian repository mirror for pbuilder env bootstrap
--debug Enable debug output
--custom-apt-entry CUSTOM_APT_ENTRY
Custom APT entry
--custom-apt-key CUSTOM_APT_KEY
Custom APT key file
.. _Docker: https://www.docker.com
.. _VyOS DockerHub organisation: https://hub.docker.com/u/vyos
.. _repository: https://github.com/vyos/vyos-build
|
