1.. _faq: 2 3FAQ 4*** 5 6How do I get help? 7================== 8 9Having trouble? We would like to help! 10 11- First go through this page with answers to common questions 12- Use the search bar at the upper left to search these docs 13- Ask a question in the ``#cloud-init`` IRC channel on Libera 14- Join and ask questions on the `cloud-init mailing list <https://launchpad.net/~cloud-init>`_ 15- Find a bug? Check out the :ref:`reporting_bugs` topic for 16 how to report one 17 18Where are the logs? 19=================== 20 21Cloud-init uses two files to log to: 22 23- `/var/log/cloud-init-output.log`: captures the output from each stage of 24 cloud-init when it runs 25- `/var/log/cloud-init.log`: very detailed log with debugging output, 26 detailing each action taken 27- `/run/cloud-init`: contains logs about how cloud-init decided to enable or 28 disable itself, as well as what platforms/datasources were detected. These 29 logs are most useful when trying to determine what cloud-init ran or did not 30 run. 31 32Be aware that each time a system boots, new logs are appended to the files in 33`/var/log`. Therefore, the files may have more than one boot worth of 34information present. 35 36When reviewing these logs look for any errors or Python tracebacks to check 37for any errors. 38 39Where are the configuration files? 40================================== 41 42Cloud-init config is provided in two places: 43 44- `/etc/cloud/cloud.cfg` 45- `/etc/cloud/cloud.cfg.d/*.cfg` 46 47These files can define the modules that run during instance initialization, 48the datasources to evaluate on boot, and other settings. 49 50Where are the data files? 51========================= 52 53Inside the `/var/lib/cloud/` directory there are two important subdirectories: 54 55instance 56-------- 57 58The `/var/lib/cloud/instance` directory is a symbolic link that points 59to the most recenlty used instance-id directory. This folder contains the 60information cloud-init received from datasources, including vendor and user 61data. This can be helpful to review to ensure the correct data was passed. 62 63It also contains the `datasource` file that containers the full information 64about what datasource was identified and used to setup the system. 65 66Finally, the `boot-finished` file is the last thing that cloud-init does. 67 68data 69---- 70 71The `/var/lib/cloud/data` directory contain information related to the 72previous boot: 73 74* `instance-id`: id of the instance as discovered by cloud-init. Changing 75 this file has no effect. 76* `result.json`: json file will show both the datasource used to setup 77 the instance, and if any errors occured 78* `status.json`: json file shows the datasource used and a break down 79 of all four modules if any errors occured and the start and stop times. 80 81What datasource am I using? 82=========================== 83 84To correctly setup an instance, cloud-init must correctly identify the 85cloud that it is on. Therefore knowing what datasource is used on an 86instance launch can help aid in debugging. 87 88To find what datasource is getting used run the `cloud-id` command: 89 90.. code-block:: shell-session 91 92 $ cloud-id 93 nocloud 94 95If the cloud-id is not what is expected, then running the `ds-identify` 96script in debug mode and providing that in a bug can help aid in resolving 97any issues: 98 99.. code-block:: shell-session 100 101 $ sudo DEBUG_LEVEL=2 DI_LOG=stderr /usr/lib/cloud-init/ds-identify --force 102 103The force parameter allows the command to be run again since the instance has 104already launched. The other options increase the verbosity of logging and 105put the logs to STDERR. 106 107How can I re-run datasource detection and cloud-init? 108===================================================== 109 110If a user is developing a new datasource or working on debugging an issue it 111may be useful to re-run datasource detection and the initial setup of 112cloud-init. 113 114To do this, force ds-identify to re-run, clean up any logs, and re-run 115cloud-init: 116 117.. code-block:: shell-session 118 119 $ sudo DI_LOG=stderr /usr/lib/cloud-init/ds-identify --force 120 $ sudo cloud-init clean --logs 121 $ sudo cloud-init init --local 122 $ sudo cloud-init init 123 124.. warning:: 125 126 These commands will re-run cloud-init as if this were first boot of a 127 system: this will, at the very least, cycle SSH host keys and may do 128 substantially more. Do not run these commands on production systems. 129 130How can I debug my user data? 131============================= 132 133Two of the most common issues with user data, that also happens to be 134cloud-config is: 135 1361. Incorrectly formatted YAML 1372. First line does not contain `#cloud-config` 138 139To verify your YAML, we do have a short script called `validate-yaml.py`_ 140that can validate your user data offline. 141 142.. _validate-yaml.py: https://github.com/canonical/cloud-init/blob/main/tools/validate-yaml.py 143 144Another option is to run the following on an instance to debug userdata 145provided to the system: 146 147.. code-block:: shell-session 148 149 $ cloud-init devel schema --system --annotate 150 151As launching instances in the cloud can cost money and take a bit longer, 152sometimes it is easier to launch instances locally using Multipass or LXD: 153 154Multipass 155--------- 156 157`Multipass`_ is a cross-platform tool to launch Ubuntu VMs across Linux, 158Windows, and macOS. 159 160When a user launches a Multipass VM, user data can be passed by adding the 161`--cloud-init` flag and the appropriate YAML file containing user data: 162 163.. code-block:: shell-session 164 165 $ multipass launch bionic --name test-vm --cloud-init userdata.yaml 166 167Multipass will validate the YAML syntax of the cloud-config file before 168attempting to start the VM! A nice addition to help save time when 169experimenting with launching instances with various cloud-configs. 170 171Multipass only supports passing user-data and only as YAML cloud-config 172files. Passing a script, a MIME archive, or any of the other user-data 173formats cloud-init supports will result in an error from the YAML syntax 174validator. 175 176.. _Multipass: https://multipass.run/ 177 178LXD 179--- 180 181`LXD`_ offers a streamlined user experience for using linux system 182containers. With LXD, a user can pass: 183 184* user data 185* vendor data 186* metadata 187* network configuration 188 189The following initializes a container with user data: 190 191.. code-block:: shell-session 192 193 $ lxc init ubuntu-daily:bionic test-container 194 $ lxc config set test-container user.user-data - < userdata.yaml 195 $ lxc start test-container 196 197To avoid the extra commands this can also be done at launch: 198 199.. code-block:: shell-session 200 201 $ lxc launch ubuntu-daily:bionic test-container --config=user.user-data="$(cat userdata.yaml)" 202 203Finally, a profile can be setup with the specific data if a user needs to 204launch this multiple times: 205 206.. code-block:: shell-session 207 208 $ lxc profile create dev-user-data 209 $ lxc profile set dev-user-data user.user-data - < cloud-init-config.yaml 210 $ lxc launch ubuntu-daily:bionic test-container -p default -p dev-user-data 211 212The above examples all show how to pass user data. To pass other types of 213configuration data use the config option specified below: 214 215+----------------+---------------------+ 216| Data | Config Option | 217+================+=====================+ 218| user data | user.user-data | 219+----------------+---------------------+ 220| vendor data | user.vendor-data | 221+----------------+---------------------+ 222| metadata | user.meta-data | 223+----------------+---------------------+ 224| network config | user.network-config | 225+----------------+---------------------+ 226 227See the LXD `Instance Configuration`_ docs for more info about configuration 228values or the LXD `Custom Network Configuration`_ document for more about 229custom network config. 230 231.. _LXD: https://linuxcontainers.org/ 232.. _Instance Configuration: https://linuxcontainers.org/lxd/docs/master/instances 233.. _Custom Network Configuration: https://linuxcontainers.org/lxd/docs/master/cloud-init 234 235cloud-localds 236------------- 237 238The `cloud-localds` command from the `cloud-utils`_ package generates a disk 239with user supplied data. The NoCloud datasouce allows users to provide their 240own user data, metadata, or network configuration directly to an instance 241without running a network service. This is helpful for launching local cloud 242images with QEMU for example. 243 244The following is an example of creating the local disk using the cloud-localds 245command: 246 247.. code-block:: shell-session 248 249 $ cat >user-data <<EOF 250 #cloud-config 251 password: password 252 chpasswd: 253 expire: False 254 ssh_pwauth: True 255 ssh_authorized_keys: 256 - ssh-rsa AAAA...UlIsqdaO+w== 257 EOF 258 $ cloud-localds seed.img user-data 259 260The resulting seed.img can then get passed along to a cloud image containing 261cloud-init. Below is an example of passing the seed.img with QEMU: 262 263.. code-block:: shell-session 264 265 $ qemu-system-x86_64 -m 1024 -net nic -net user \ 266 -hda ubuntu-20.04-server-cloudimg-amd64.img \ 267 -hdb seed.img 268 269The now booted image will allow for login using the password provided above. 270 271For additional configuration, users can provide much more detailed 272configuration, including network configuration and metadata: 273 274.. code-block:: shell-session 275 276 $ cloud-localds --network-config=network-config-v2.yaml \ 277 seed.img userdata.yaml metadata.yaml 278 279See the :ref:`network_config_v2` page for details on the format and config of 280network configuration. To learn more about the possible values for metadata, 281check out the :ref:`nocloud` page. 282 283.. _cloud-utils: https://github.com/canonical/cloud-utils/ 284 285Where can I learn more? 286======================================== 287 288Below are some videos, blog posts, and white papers about cloud-init from a 289variety of sources. 290 291- `cloud-init - The Good Parts`_ 292- `cloud-init Summit 2019`_ 293- `Utilising cloud-init on Microsoft Azure (Whitepaper)`_ 294- `Cloud Instance Initialization with cloud-init (Whitepaper)`_ 295- `cloud-init Summit 2018`_ 296- `cloud-init - The cross-cloud Magic Sauce (PDF)`_ 297- `cloud-init Summit 2017`_ 298- `cloud-init - Building clouds one Linux box at a time (Video)`_ 299- `cloud-init - Building clouds one Linux box at a time (PDF)`_ 300- `Metadata and cloud-init`_ 301- `The beauty of cloud-init`_ 302- `Introduction to cloud-init`_ 303 304.. _cloud-init - The Good Parts: https://www.youtube.com/watch?v=2_m6EUo6VOI 305.. _cloud-init Summit 2019: https://powersj.io/post/cloud-init-summit19/ 306.. _Utilising cloud-init on Microsoft Azure (Whitepaper): https://ubuntu.com/engage/azure-cloud-init-whitepaper 307.. _Cloud Instance Initialization with cloud-init (Whitepaper): https://ubuntu.com/blog/cloud-instance-initialisation-with-cloud-init 308.. _cloud-init Summit 2018: https://powersj.io/post/cloud-init-summit18/ 309.. _cloud-init - The cross-cloud Magic Sauce (PDF): https://events.linuxfoundation.org/wp-content/uploads/2017/12/cloud-init-The-cross-cloud-Magic-Sauce-Scott-Moser-Chad-Smith-Canonical.pdf 310.. _cloud-init Summit 2017: https://powersj.io/post/cloud-init-summit17/ 311.. _cloud-init - Building clouds one Linux box at a time (Video): https://www.youtube.com/watch?v=1joQfUZQcPg 312.. _cloud-init - Building clouds one Linux box at a time (PDF): https://annex.debconf.org/debconf-share/debconf17/slides/164-cloud-init_Building_clouds_one_Linux_box_at_a_time.pdf 313.. _Metadata and cloud-init: https://www.youtube.com/watch?v=RHVhIWifVqU 314.. _The beauty of cloud-init: http://brandon.fuller.name/archives/2011/05/02/06.40.57/ 315.. _Introduction to cloud-init: http://www.youtube.com/watch?v=-zL3BdbKyGY 316 317.. vi: textwidth=79 318