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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
:lastproofread: 2021-07-12
.. _cloud-init:
###############
VyOS cloud-init
###############
Cloud and virtualized instances of VyOS are initialized using the
industry-standard cloud-init. Via cloud-init, the system performs tasks such as
injecting SSH keys and configuring the network. In addition, the user can supply
a custom configuration at the time of instance launch.
**************
Config Sources
**************
VyOS support three types of config sources.
* Metadata - Metadata is sourced by the cloud platform or hypervisor.
In some clouds, there is implemented as an HTTP endpoint at
``http://169.254.169.254``.
* Network configuration - This config source informs the system about the
network settings like IP addresses, routes, DNS. Available only in several
cloud and virtualization platforms.
* User-data - User-data is specified by the user. This config source offers the
ability to insert any CLI configuration commands into the configuration before
the first boot.
*********
User-data
*********
Major cloud providers offer a means of providing user-data at the time of
instance launch. It can be provided as plain text or as base64-encoded text,
depending on cloud provider. Also, it can be compressed using gzip, which makes
sense with a long configuration commands list, because of the hard limit to
~16384 bytes for the whole user-data.
The easiest way to configure the system via user-data is the Cloud-config syntax
described below.
********************
Cloud-config modules
********************
In VyOS, by default, enables only two modules:
* ``write_files`` - this module allows to insert any files into the filesystem
before the first boot, for example, pre-generated encryption keys,
certificates, or even a whole ``config.boot`` file.
* ``vyos_userdata`` - the module accepts a list of CLI configuration commands in
a ``vyos_config_commands`` section, which gives an easy way to configure the
system during deployment.
************************
cloud-config file format
************************
A cloud-config document is written in YAML. The file must begin
with ``#cloud-config`` line. The only supported top-level keys are
``vyos_config_commands`` and ``write_files``. The use of these keys is described
in the following two sections.
************************
Initial Configuration
************************
The key used to designate a VyOS configuration is ``vyos_config_commands``. What
follows is VyOS configuration using the "set-style" syntax. Both "set" and "delete"
commands are supported.
Commands requirements:
* one command per line
* if command ends in a value, it must be inside single quotes
* a single-quote symbol is not allowed inside command or value
The commands list produced by the ``show configuration commands`` command on a
VyOS router should comply with all the requirements, so it is easy to get a
proper commands list by copying it from another router.
The configuration specified in the cloud-config document overwrites default
configuration values and values configured via Metadata.
Here is an example cloud-config that appends configuration at the time of first boot.
.. code-block:: yaml
#cloud-config
vyos_config_commands:
- set system host-name 'vyos-prod-ashburn'
- set system ntp server 1.pool.ntp.org
- set system ntp server 2.pool.ntp.org
- delete interfaces ethernet eth1 address 'dhcp'
- set interfaces ethernet eth1 address '192.0.2.247/24'
- set protocols static route 198.51.100.0/24 next-hop '192.0.2.1'
-------------------------
System Defaults/Fallbacks
-------------------------
These are the VyOS defaults and fallbacks.
* SSH is configured on port 22
* ``vyos``/``vyos`` credentials if no others specified by data source
* DHCP on first Ethernet interface if no network configuration is provided
All of these can be overridden using the configuration in user-data.
*********************************
Command Execution at Initial Boot
*********************************
VyOS supports the execution of operational commands and linux commands at
initial boot. This is accomplished using ``write_files`` to certain
files in the /opt/vyatta/etc/config/scripts directory. Commands specified
in opt/vyatta/etc/config/scripts/vyos-preconfig-bootup.script are executed
prior to configuration. The
/opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script file contains
commands to be executed after configuration. In both cases, commands are
executed as the root user.
Note that the /opt/vyatta/etc/config is used instead of the /config/scripts
directory referenced in the :ref:`command-scripting` section of the
documentation because the /config/script directory isn't mounted when the
``write_files`` module executes.
The following example shows how to execute commands after the initial
configuration.
.. code-block:: yaml
#cloud-config
write_files:
- path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
owner: root:vyattacfg
permissions: '0775'
content: |
#!/bin/vbash
source /opt/vyatta/etc/functions/script-template
filename=/tmp/bgp_status_`date +"%Y_%m_%d_%I_%M_%p"`.log
run show ip bgp summary >> $filename
If you need to gather information from linux commands to configure VyOS, you can
execute commands and then configure VyOS in the same script.
The following example sets the hostname based on the instance identifier
obtained from the EC2 metadata service.
.. code-block:: yaml
#cloud-config
write_files:
- path: /opt/vyatta/etc/config/scripts/vyos-postconfig-bootup.script
owner: root:vyattacfg
permissions: '0775'
content: |
#!/bin/vbash
source /opt/vyatta/etc/functions/script-template
hostname=`curl -s http://169.254.169.254/latest/meta-data/instance-id`
configure
set system host-name $hostname
commit
exit
*******
NoCloud
*******
Injecting configuration data is not limited to cloud platforms. Users can
employ the NoCloud data source to inject user-data and meta-data on
virtualization platforms such as VMware, Hyper-V and KVM.
While other methods exist, the most straightforward method for using the
NoCloud data source is creating a seed ISO and attaching it to the virtual
machine as a CD drive. The volume must be formatted as a vfat or ISO 9660
file system with the label "cidata" or "CIDATA".
Create text files named user-data and meta-data. On linux-based systems,
the mkisofs utility can be used to create the seed ISO. The following
syntax will add these files to the ISO 9660 file system.
.. code-block:: none
mkisofs -joliet -rock -volid "cidata" -output seed.iso meta-data user-data
The seed.iso file can be attached to the virtual machine. As an example,
the method with KVM to attach the ISO as a CD drive follows.
.. code-block:: none
$ virt-install -n vyos_r1 \
--ram 4096 \
--vcpus 2 \
--cdrom seed.iso \
--os-type linux \
--os-variant debian10 \
--network network=default \
--graphics vnc \
--hvm \
--virt-type kvm \
--disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \
--import \
--noautoconsole
For more information on the NoCloud data source, visit its
`page <https://cloudinit.readthedocs.io/en/latest/topics/datasources/nocloud.html>`_
in the cloud-init documentation.
***************
Troubleshooting
***************
If you encounter problems, verify that the cloud-config document contains
valid YAML. Online resources such as https://yamlvalidator.com/ provide
a simple tool for validating YAML.
cloud-init logs to /var/log/cloud-init.log. This file can be helpful in
determining why the configuration varies from what you expect. You can fetch the
most important data filtering output for ``vyos`` keyword:
.. code-block:: none
sudo grep vyos /var/log/cloud-init.log
|
