From c8dd424f89353fd1d3e927745369b9bf6a061865 Mon Sep 17 00:00:00 2001 From: Rob Szumski Date: Fri, 14 Mar 2014 11:33:00 -0700 Subject: [PATCH] refactor(docs): rearrange order and add full example --- Documentation/cloud-config.md | 246 ++++++++++++++-------------------- 1 file changed, 104 insertions(+), 142 deletions(-) diff --git a/Documentation/cloud-config.md b/Documentation/cloud-config.md index f6c211d..a3c7da9 100644 --- a/Documentation/cloud-config.md +++ b/Documentation/cloud-config.md @@ -1,111 +1,27 @@ -# Customize CoreOS with Cloud-Config +# Customize with Cloud-Config -CoreOS allows you to configure machine parameters, launch systemd units on startup and more. Only a subset of [cloud-config functionality][cloud-config] is implemented. A set of custom parameters were added to the cloud-config format that are specific to CoreOS. +CoreOS allows you to configure networking, create users, launch systemd units on startup and more. We've designed our implementation to allow the same cloud-config file to work across all of our supported platforms. + +Only a subset of [cloud-config functionality][cloud-config] is implemented. A set of custom parameters were added to the cloud-config format that are specific to CoreOS. An example file containing all available options can be found at the bottom of this page. [cloud-config]: http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data -## Supported cloud-config Parameters +## CoreOS Parameters -### ssh_authorized_keys +### coreos.etcd.discovery_url -Provided public SSH keys will be authorized for the `core` user. - -The keys will be named "coreos-cloudinit" by default. -Override this with the `--ssh-key-name` flag when calling `coreos-cloudinit`. - -### hostname - -The provided value will be used to set the system's hostname. -This is the local part of a fully-qualified domain name (i.e. `foo` in `foo.example.com`). - -### users - -Add or modify users with the `users` directive by providing a list of user objects, each consisting of the following fields. -Each field is optional and of type string unless otherwise noted. -All but the `passwd` and `ssh-authorized-keys` fields will be ignored if the user already exists. - -- **name**: Required. Login name of user -- **gecos**: GECOS comment of user -- **passwd**: Hash of the password to use for this user -- **homedir**: User's home directory. Defaults to /home/ -- **no-create-home**: Boolean. Skip home directory createion. -- **primary-group**: Default group for the user. Defaults to a new group created named after the user. -- **groups**: Add user to these additional groups -- **no-user-group**: Boolean. Skip default group creation. -- **ssh-authorized-keys**: List of public SSH keys to authorize for this user -- **system**: Create the user as a system user. No home directory will be created. -- **no-log-init**: Boolean. Skip initialization of lastlog and faillog databases. - -The following fields are not yet implemented: - -- **inactive**: Deactivate the user upon creation -- **lock-passwd**: Boolean. Disable password login for user -- **sudo**: Entry to add to /etc/sudoers for user. By default, no sudo access is authorized. -- **selinux-user**: Corresponding SELinux user -- **ssh-import-id**: Import SSH keys by ID from Launchpad. - -##### Generating a password hash - -Generating a safe hash is important to the security of your system. Currently with updated tools like [oclhashcat](http://hashcat.net/oclhashcat/) simplified hashes like md5crypt are trivial to crack on modern GPU hardware. You can generate a "safer" hash (read: not safe, never publish your hashes publicly) via: - -###### On Debian/Ubuntu (via the package "whois") - mkpasswd --method=SHA-512 --rounds=4096 - -###### With OpenSSL (note: this will only make md5crypt. While better than plantext it should not be considered fully secure) - openssl passwd -1 - -###### With Python (change password and salt values) - python -c "import crypt, getpass, pwd; print crypt.crypt('password', '\$6\$SALT\$')" - -###### With Perl (change password and salt values) - perl -e 'print crypt("password","\$6\$SALT\$") . "\n"' - -Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms. - -### write_files - -Inject an arbitrary set of files to the local filesystem. -Provide a list of objects with the following attributes: - -- **path**: Absolute location on disk where contents should be written -- **content**: Data to write at the provided `path` -- **permissions**: String representing file permissions in octal notation (i.e. '0644') -- **owner**: User and group that should own the file written to disk. This is equivalent to the `:` argument to `chown : `. - -## Custom cloud-config Parameters - -### coreos.etcd - -The `coreos.etcd.*` options are translated to a partial systemd unit acting as an etcd configuration file. -`coreos-cloudinit` will also replace the strings `$private_ipv4` and `$public_ipv4` with the values generated by CoreOS based on a given provider. - -For example, the following cloud-config document... +The value of `coreos.etcd.discovery_url` will be used to discover the instance's etcd peers using the [etcd discovery protocol][disco-proto]. Usage of the [public discovery service][disco-service] is encouraged. **Note:** this is currently Amazon-only. ``` #cloud-config coreos: - etcd: - name: node001 - discovery: https://discovery.etcd.io/3445fa65423d8b04df07f59fb40218f8 - bind-addr: $public_ipv4:4001 - peer-bind-addr: $private_ipv4:7001 + etcd: + discovery_url: https://discovery.etcd.io/827c73219eeb2fa5530027c37bf18877 ``` -...will generate a systemd snippet like this: - -``` -[Service] -Environment="ETCD_NAME=node001"" -Environment="ETCD_DISCOVERY=https://discovery.etcd.io/3445fa65423d8b04df07f59fb40218f8" -Environment="ETCD_BIND_ADDR=203.0.113.29:4001" -Environment="ETCD_PEER_BIND_ADDR=192.0.2.13:7001" -``` - -For more information about the available configuration options, see the [etcd documentation][etcd-config]. -Note that hyphens in the coreos.etcd.* keys are mapped to underscores. - -[etcd-config]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md +[disco-proto]: https://github.com/coreos/etcd/blob/master/Documentation/discovery-protocol.md +[disco-service]: http://discovery.etcd.io ### coreos.units @@ -116,35 +32,6 @@ Arbitrary systemd units may be provided in the `coreos.units` attribute. - **runtime**: boolean indicating whether or not to persist the unit across reboots. This is analagous to the `--runtime` flag to `systemd enable`. - **content**: plaintext string representing entire unit file -See docker example below. - -## user-data Script - -Simply set your user-data to a script where the first line is a shebang: - -``` -#!/bin/bash - -echo 'Hello, world!' -``` - -## Examples - -### Inject an SSH key, bootstrap etcd, and start fleet -``` -#cloud-config - -coreos: - etcd: - discovery: https://discovery.etcd.io/827c73219eeb2fa5530027c37bf18877 - fleet: - autostart: yes -ssh_authorized_keys: - - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... -``` - -### Start a docker container on boot - ``` #cloud-config @@ -166,33 +53,108 @@ coreos: WantedBy=local.target ``` -### Add a user +## Cloud-Config Parameters + +### ssh_authorized_keys + +Provided public SSH keys will be authorized for the `core` user. + +The keys will be named "coreos-cloudinit" by default. +Override this with the `--ssh-key-name` flag when calling `coreos-cloudinit`. + +``` +#cloud-config + +ssh_authorized_keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... +``` + +### hostname + +The provided value will be used to set the system's hostname. +This is the local part of a fully-qualified domain name (i.e. `foo` in `foo.example.com`). + +``` +#cloud-config + +hostname: coreos1 +``` + +### users + +Add or modify users with the `users` directive by providing a list of user objects, each consisting of the following fields. +Each field is optional and of type string unless otherwise noted. +All but the `passwd` and `ssh-authorized-keys` fields will be ignored if the user already exists. + +- **name**: Required. Login name of user +- **gecos**: GECOS comment of user +- **passwd**: Hash of the password to use for this user +- **homedir**: User's home directory. Defaults to /home/ +- **no-create-home**: Boolean. Skip home directory creation. +- **primary-group**: Default group for the user. Defaults to a new group created named after the user. +- **groups**: Add user to these additional groups +- **no-user-group**: Boolean. Skip default group creation. +- **ssh-authorized-keys**: List of public SSH keys to authorize for this user +- **system**: Create the user as a system user. No home directory will be created. +- **no-log-init**: Boolean. Skip initialization of lastlog and faillog databases. + +The following fields are not yet implemented: + +- **inactive**: Deactivate the user upon creation +- **lock-passwd**: Boolean. Disable password login for user +- **sudo**: Entry to add to /etc/sudoers for user. By default, no sudo access is authorized. +- **selinux-user**: Corresponding SELinux user +- **ssh-import-id**: Import SSH keys by ID from Launchpad. ``` #cloud-config users: - name: elroy - passwd: $6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm... - groups: - - staff - - docker - ssh-authorized-keys: - - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... + passwd: $6$5s2u6/jR$un0AvWnqilcgaNB3Mkxd5yYv6mTlWfOoCYHZmfi3LDKVltj.E8XNKEcwWm... + groups: + - staff + - docker + ssh-authorized-keys: + - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... ``` -### Inject configuration files +#### Generating a password hash + +If you choose to use a password instead of an SSH key, generating a safe hash is extremely important to the security of your system. Simplified hashes like md5crypt are trivial to crack on modern GPU hardware. Here are a few ways to generate secure hashes: ``` -#cloud-config +# On Debian/Ubuntu (via the package "whois") +mkpasswd --method=SHA-512 --rounds=4096 -write_files: - - path: /etc/hosts - contents: | - 127.0.0.1 localhost - 192.0.2.211 buildbox - - path: /etc/resolv.conf - contents: | - nameserver 192.0.2.13 - nameserver 192.0.2.14 +# OpenSSL (note: this will only make md5crypt. While better than plantext it should not be considered fully secure) +openssl passwd -1 + +# Python (change password and salt values) +python -c "import crypt, getpass, pwd; print crypt.crypt('password', '\$6\$SALT\$')" + +# Perl (change password and salt values) +perl -e 'print crypt("password","\$6\$SALT\$") . "\n"' ``` + +Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms. + +### write_files + +Inject an arbitrary set of files to the local filesystem. +Provide a list of objects with the following attributes: + +- **path**: Absolute location on disk where contents should be written +- **content**: Data to write at the provided `path` +- **permissions**: String representing file permissions in octal notation (i.e. '0644') +- **owner**: User and group that should own the file written to disk. This is equivalent to the `:` argument to `chown : `. + +## user-data Script + +Simply set your user-data to a script where the first line is a shebang: + +``` +#!/bin/bash + +echo 'Hello, world!' +``` \ No newline at end of file