rancher/os
1
0
Fork 1
mirror of https://github.com/rancher/os.git synced 2025-09-09 10:40:30 +00:00
Code Issues Releases Wiki Activity

import the rancherOS docs so we can write docs for the next release

Browse Source 
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
This commit is contained in:
Sven Dowideit
2016-11-02 11:57:09 +10:00
parent 35ce5cd8b5
commit 980ee23130
197 changed files with 45993 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/os/amazon-ecs/index.md Normal file
View File

@@ -0,0 +1,77 @@
---
title: Amazon ECS on RancherOS
layout: os-default
---
## Amazon ECS (EC2 Container Service)
---
[Amazon ECS](https://aws.amazon.com/ecs/) is supported, which allows RancherOS EC2 instances to join your cluster.
### Pre-Requisites
Prior to launching RancherOS EC2 instances, the [ECS Container Instance IAM Role](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html) will need to have been created. This `ecsInstanceRole` will need to be used when launching EC2 instances. If you have been using ECS, you created this role if you followed the ECS "Get Started" interactive guide.
### Launching an instance with ECS
RancherOS makes it easy to join your ECS cluster. The ECS agent is a [system service]({{site.baseurl}}/os/system-services/adding-system-services/) that is enabled in the ECS enabled AMI. There may be other RancherOS AMIs that don't have the ECS agent enabled by default, but it can easily be added in the user data on any RancherOS AMI.
When launching the RancherOS AMI, you'll need to specify the **IAM Role** and **Advanced Details** -> **User Data** in the **Configure Instance Details** step.
For the **IAM Role**, you'll need to be sure to select the ECS Container Instance IAM role.
For the **User Data**, you'll need to pass in the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file.
```yaml
#cloud-config
rancher:
environment:
ECS_CLUSTER: your-ecs-cluster-name
# If you have selected a RancherOS AMI that does not have ECS enabled by default,
# you'll need to enable the system service for the ECS agent.
services_include:
amazon-ecs-agent: true
```
#### Version
By default, the ECS agent will be using the `latest` tag for the `amazon-ecs-agent` image. In v0.5.0, we introduced the ability to select which version of the `amazon-ecs-agent`.
To select the version, you can update your [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file.
```yaml
#cloud-config
rancher:
environment:
ECS_CLUSTER: your-ecs-cluster-name
# Note: You will need to make sure to include the colon in front of the version.
ECS_AGENT_VERSION: :v1.9.0
# If you have selected a RancherOS AMI that does not have ECS enabled by default,
# you'll need to enable the system service for the ECS agent.
services_include:
amazon-ecs-agent: true
```
<br>
> **Note:** The `:` must be in front of the version tag in order for the ECS image to be tagged correctly.
### Amazon ECS enabled AMIs
Latest Release: [v0.7.0](https://github.com/rancher/os/releases/tag/v0.7.0)
Region | Type | AMI
---|--- | ---
ap-northeast-1 | HVM - ECS Enabled | [ami-dee442bf](https://console.aws.amazon.com/ec2/home?region=ap-northeast-1#launchInstanceWizard:ami=ami-dee442bf)
ap-northeast-2 | HVM - ECS Enabled | [ami-84ff2bea](https://console.aws.amazon.com/ec2/home?region=ap-northeast-2#launchInstanceWizard:ami=ami-84ff2bea)
ap-south-1 | HVM - ECS Enabled | [ami-796b1f16](https://console.aws.amazon.com/ec2/home?region=ap-south-1#launchInstanceWizard:ami=ami-796b1f16)
ap-southeast-1 | HVM - ECS Enabled | [ami-5749ef34](https://console.aws.amazon.com/ec2/home?region=ap-southeast-1#launchInstanceWizard:ami=ami-5749ef34)
ap-southeast-2 | HVM - ECS Enabled | [ami-4c55682f](https://console.aws.amazon.com/ec2/home?region=ap-southeast-2#launchInstanceWizard:ami=ami-4c55682f)
eu-central-1 | HVM - ECS Enabled | [ami-632ed70c](https://console.aws.amazon.com/ec2/home?region=eu-central-1#launchInstanceWizard:ami=ami-632ed70c)
eu-west-1 | HVM - ECS Enabled | [ami-b3f3bcc0](https://console.aws.amazon.com/ec2/home?region=eu-west-1#launchInstanceWizard:ami=ami-b3f3bcc0)
sa-east-1 | HVM - ECS Enabled | [ami-f8158894](https://console.aws.amazon.com/ec2/home?region=sa-east-1#launchInstanceWizard:ami=ami-f8158894)
us-east-1 | HVM - ECS Enabled | [ami-e3bfeff4](https://console.aws.amazon.com/ec2/home?region=us-east-1#launchInstanceWizard:ami=ami-e3bfeff4)
us-east-2 | HVM - ECS Enabled | [ami-883a60ed](https://console.aws.amazon.com/ec2/home?region=us-east-1#launchInstanceWizard:ami=ami-883a60ed)
us-west-1 | HVM - ECS Enabled | [ami-9cf4bcfc](https://console.aws.amazon.com/ec2/home?region=us-west-1#launchInstanceWizard:ami=ami-9cf4bcfc)
us-west-2 | HVM - ECS Enabled | [ami-4906a329](https://console.aws.amazon.com/ec2/home?region=us-west-2#launchInstanceWizard:ami=ami-4906a329)

137
docs/os/configuration/custom-console/index.md Normal file
View File

@@ -0,0 +1,137 @@
---
title: Custom Console on RancherOS
layout: os-default
---
## Custom Console
---
When [booting from the ISO]({{site.baseurl}}/os/running-rancheros/workstation/boot-from-iso/), RancherOS starts with the default console, which is based on busybox.
You can select which console you want RancherOS to start with using the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
### Enabling Consoles using Cloud-Config
When launching RancherOS with a [cloud-config]({[site.baseurl}}/os/configuration/#cloud-config) file, you can select which console you want to use.
Currently, the list of available consoles are:
* default
* centos
* debian
* fedora
* ubuntu
Here is an example cloud-config file that can be used to enable the debian console.
```yaml
#cloud-config
rancher:
console: debian
```
### Listing Available Consoles
You can easily list the available consoles in RancherOS and what their status is with `sudo ros console list`.
```
$ sudo ros console list
disabled centos
disabled debian
current default
disabled fedora
disabled ubuntu
```
### Changing Consoles after RancherOS has started
You can view which console is being used by RancherOS by checking which console container is running in System Docker. If you wanted to switch consoles, you just need to run a simple command and select your new console.
For our example, we'll switch to the Ubuntu console.
```
$ sudo ros console switch ubuntu
Switching consoles will
1. destroy the current console container
2. log you out
3. restart Docker
Continue [y/N]:y
Pulling console (rancher/os-ubuntuconsole:v0.5.0-3)...
v0.5.0-3: Pulling from rancher/os-ubuntuconsole
6d3a6d998241: Pull complete
606b08bdd0f3: Pull complete
1d99b95ffc1c: Pull complete
a3ed95caeb02: Pull complete
3fc2f42db623: Pull complete
2fb84911e8d2: Pull complete
fff5d987b31c: Pull complete
e7849ae8f782: Pull complete
de375d40ae05: Pull complete
8939c16614d1: Pull complete
Digest: sha256:37224c3964801d633ea8b9629137bc9d4a8db9d37f47901111b119d3e597d15b
Status: Downloaded newer image for rancher/os-ubuntuconsole:v0.5.0-3
switch-console_1 | time="2016-07-02T01:47:14Z" level=info msg="Project [os]: Starting project "
switch-console_1 | time="2016-07-02T01:47:14Z" level=info msg="[0/18] [console]: Starting "
switch-console_1 | time="2016-07-02T01:47:14Z" level=info msg="Recreating console"
Connection to 127.0.0.1 closed by remote host.
```
<br>
After logging back, you'll be in the Ubuntu console.
```
$ sudo system-docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6bf33541b2dc rancher/os-ubuntuconsole:v0.5.0-rc3 "/usr/sbin/entry.sh /" About a minute ago Up About a minute
```
<br>
> **Note:** When switching between consoles, the currently running console container is destroyed, Docker is restarted and you will be logged out.
### Console persistence
All consoles except the default (busybox) console are persistent. Persistent console means that the console container will remain the same and preserves changes made to its filesystem across reboots. If a container is deleted/rebuilt, state in the console will be lost except what is in the persisted directories.
```
/home
/opt
/var/lib/docker
/var/lib/rancher
```
<br>
> **Note:** When using a persistent console and in the current version's console, [rolling back]({{site.baseurl}}/os/upgrading/#rolling-back-an-upgrade) is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.
### Enabling Consoles
You can also enable a console that will be changed at the next reboot.
For our example, we'll switch to the Debian console.
```
# Check the console running in System Docker
$ sudo system-docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
95d548689e82 rancher/os-docker:v0.5.0 "/usr/sbin/entry.sh /" About an hour ago Up About an hour docker
# Enable the Debian console
$ sudo ros console enable debian
Pulling console (rancher/os-debianconsole:v0.5.0-3)...
v0.5.0-3: Pulling from rancher/os-debianconsole
7268d8f794c4: Pull complete
a3ed95caeb02: Pull complete
21cb8a645d75: Pull complete
5ee1d288a088: Pull complete
c09f41c2bd29: Pull complete
02b48ce40553: Pull complete
38a4150e7e9c: Pull complete
Digest: sha256:5dbca5ba6c3b7ba6cd6ac75a1d054145db4b4ea140db732bfcbd06f17059c5d0
Status: Downloaded newer image for rancher/os-debianconsole:v0.5.0-3
```
<br>
At the next reboot, RancherOS will be using the Debian console.

99
docs/os/configuration/custom-kernels/index.md Normal file
View File

@@ -0,0 +1,99 @@
---
title: Custom Kernels in RancherOS
layout: os-default
---
## Custom Kernels
### Changing the Kernel in RancherOS
By default, RancherOS ships with the kernel provided by the [os-kernel repository](https://github.com/rancher/os-kernel). Swapping out the default kernel can by done by [building your own custom RancherOS ISO]({{site.baseurl}}/os/configuration/custom-rancheros-iso/).
1. Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
```
$ git clone https://github.com/rancher/os.git
```
2. In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` will need to be updated. Using your favorite editor, replace the appropriate `KERNEL_URL` value with a URL of your compiled custom kernel tarball. Ideally, the URL will use `HTTPS`.
`Dockerfile.dapper` file
```
# Update the URL to your own custom kernel tarball
ARG KERNEL_URL_amd64=https://github.com/rancher/os-kernel/releases/download/Ubuntu-4.4.0-23.41-rancher/linux-4.4.10-rancher-x86.tar.gz
ARG KERNEL_URL_arm64=https://github.com/imikushin/os-kernel/releases/download/Estuary-4.1.18-arm64-3/linux-4.1.18-arm64.tar.gz
```
<br>
> **Note:** `KERNEL_URL` settings should point to a Linux kernel, compiled and packaged in a specific way. You can fork [os-kernel repository](https://github.com/rancher/os-kernel) to package your own kernel.
Your kernel should be packaged and published as a set of files of the following format:
`<kernel-name-and-version>.tar.gz` is the one KERNEL_URL should point to. It contains the kernel binary, core modules and firmware:
```
boot/
vmlinuz-<kernel-version>
lib/
modules/
<kernel-version>/
...
firmware/
...
```
`build.tar.gz` contains build headers to build additional modules (e.g. using DKMS): it is a subset of the kernel sources tarball. These files will be installed into `/usr/src/<os-kernel-tag>` using the `kernel-headers-system-docker` and `kernel-headers` services.
`extra.tar.gz` contains extra modules and firmware for your kernel and should be built into a `kernel-extras` service:
```
lib/
modules/
<kernel-version>/
...
firmware/
...
```
3. After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{site.baseurl}}/os/configuration/custom-rancheros-iso/).
### Packaging a Kernel to be used in RancherOS
We build the kernel for RancherOS at the [os-kernel repository](https://github.com/rancher/os-kernel). You can use this repository to help package your own custom kernel to be used in RancherOS.
1. Create a clone of the [os-kernel](https://github.com/rancher/os-kernel) repository to your local machine using `git clone`.
```
$ git clone https://github.com/rancher/os-kernel.git
```
2. In the `./scripts/build-common` file, update the `KERNEL_URL` and `KERNEL_SHA1`. `KERNEL_URL` points to Linux kernel sources archive, packaged as `.tar.gz` or `.tar.xz`. `KERNEL_SHA1` is the `SHA1` sum of the kernel sources archive.
`./scripts/build-common` file
```bash
#!/bin/bash
set -e
: ${KERNEL_URL:="https://github.com/rancher/linux/archive/Ubuntu-3.19.0-27.29.tar.gz"}
: ${KERNEL_SHA1:="84b9bc53bbb4dd465b97ea54a71a9805e27ae4f2"}
: ${ARTIFACTS:=$(pwd)/assets}
: ${BUILD:=$(pwd)/build}
: ${CONFIG:=$(pwd)/config}
: ${DIST:=$(pwd)/dist}
```
3. After you've replaced the `KERNEL_URL` and `KERNEL_SHA1`, run `make` in the root `os-kernel` directory. After the build is completed, a `./dist/kernel` directory will be created with the freshly built kernel tarball and headers.
```
$ make
$ cd dist/kernel
$ ls
build.tar.gz extra.tar.gz <name_of_kernel>.tar.gz
```
The `build.tar.gz` and `extra.tar.gz` files are used to build the `rancher/os-extras` and `rancher/os-headers` images for your RancherOS release - see https://github.com/rancher/os-images and https://github.com/rancher/os-services for how to build the images and make them available.

91
docs/os/configuration/custom-rancheros-iso/index.md Normal file
View File

@@ -0,0 +1,91 @@
---
title: Custom RancherOS ISO
layout: os-default
---
## Custom RancherOS ISO
It's easy to build your own RancherOS ISO.
1. Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
```
$ git clone https://github.com/rancher/os.git
```
2. In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` can be updated to use [custom kernels]({{site.baseurl}}/os/configuration/custom-kernels), or [custom Docker]({{site.baseurl}}/os/configuration/custom-docker).
3. After you've saved your edits, run `make` in the root directory. After the build has completed, a `./dist/artifacts` directory will be created with the custom built RancherOS release files.
Build Requirements: `bash`, `make`, `docker` (Docker version >= 1.10.3)
```
$ make
$ cd dist/artifacts
$ ls
initrd rancheros.iso
iso-checksums.txt vmlinuz
```
The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{site.baseurl}}/os/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{site.baseurl}}/os/running-rancheros/workstation/docker-machine).
### Creating a GCE Image Archive
You can build the [GCE image archive](https://cloud.google.com/compute/docs/tutorials/building-images) using [Packer](https://www.packer.io/). You will need Packer, QEMU and GNU tar installed.
First, create `gce-qemu.json`:
```json
{
"builders":
[
{
"type": "qemu",
"name": "qemu-googlecompute",
"iso_url": "https://github.com/rancherio/os/releases/download/<RancherOS-Version>/rancheros.iso",
"iso_checksum": "<rancheros.iso-MD5-hash>",
"iso_checksum_type": "md5",
"ssh_wait_timeout": "360s",
"disk_size": 10000,
"format": "raw",
"headless": true,
"accelerator": "none",
"ssh_host_port_min": 2225,
"ssh_host_port_max": 2229,
"ssh_username": "rancher",
"ssh_password": "rancher",
"ssh_port": 22,
"net_device": "virtio-net",
"disk_interface": "scsi",
"qemuargs": [
["-m", "1024M"], ["-nographic"], ["-display", "none"]
]
}
],
"provisioners": [
{
"type":"shell",
"script": "../scripts/install2disk"
}
]
}
```
NOTE: For faster builds You can use `"kvm"` as the `accelerator` field value if you have KVM, but that's optional.
Run:
```
$ packer build gce-qemu.json
```
Packer places its output into `output-qemu-googlecompute/packer-qemu-googlecompute` - it's a raw VM disk image. Now you just need to name it `disk.raw` and package it as sparse .tar.gz:
```
$ mv output-qemu-googlecompute/packer-qemu-googlecompute disk.raw
$ tar -czSf rancheros-<RancherOS-Version>.tar.gz disk.raw
```
NOTE: the last command should be using GNU tar. It might be named `gtar` on your system.

29
docs/os/configuration/dkms/index.md Normal file
View File

@@ -0,0 +1,29 @@
---
title: DKMS
layout: os-default
---
## DKMS
DKMS is supported by running the DKMS scripts inside a container. To compile any kernel modules, you first need to [install the kernel headers]({{site.baseurl}}/os/configuration/kernel-modules-kernel-headers/). After kernel headers are enabled, they are installed in `/lib/modules/$(uname -r)/build`. To deploy containers that runs DKMS, you will need to ensure that you bind mount in `/usr/src` and `/lib/modules`.
### Docker Example
```
# Installing Kernel Headers for Docker
$ sudo ros service enable kernel-headers
$ sudo ros service up -d kernel-headers
# Run a container in Docker and bind mount specific directories to run DKMS
$ docker run -it -v /usr/src:/usr/src -v /lib/modules:/lib/modules ubuntu:15.10 sh -c 'apt-get update && apt-get install -y sysdig-dkms'
```
### System Docker Example
```
# Installing Kernel Headers for System Docker
$ sudo ros service enable kernel-headers-system-docker
$ sudo ros service up -d kernel-headers-system-docker
# Run a container in System Docker and bind mount specific directories to run DKMS
$ sudo system-docker run -it -v /usr/src:/usr/src -v /lib/modules:/lib/modules ubuntu:15.10 sh -c 'apt-get update && apt-get install -y sysdig-dkms'
```

85
docs/os/configuration/docker/index.md Normal file
View File

@@ -0,0 +1,85 @@
---
title: Configuring Docker in RancherOS
layout: os-default
---
## Configuring Docker or System Docker
In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
### Configuring Docker
In your cloud-config, Docker configuration is located under the `rancher.docker` key.
```yaml
#cloud-config
rancher:
docker:
tls: true
tls_args: [--tlsverify, --tlscacert=ca.pem, --tlscert=server-cert.pem, --tlskey=server-key.pem, '-H=0.0.0.0:2376']
storage_driver: overlay
```
You can also customize Docker after it's been started using `ros config`.
```
$ sudo ros config set rancher.docker.storage_driver overlay
```
#### Valid Keys for Docker
Many of the standard Docker daemon arguments can be placed under the `rancher.docker` key. The command needed to start the Docker daemon will be generated based on these arguments. The following arguments are currently supported.
Key | Value
---|---
`bridge` | String
`config_file` | String
`containerd` | String
`debug` | Boolean
`exec_root` | String
`group` | String
`graph` | String
`host` | String
`live_restore` | Boolean
`log_driver` | String
`log_opts` | Map where keys and values are strings
`pid_file` | String
`registry_mirror` | String
`restart` | Boolean
`selinux_enabled` | Boolean
`storage_driver` | String
`userland_proxy` | Boolean
In addition to the standard daemon arguments, there are a few fields specific to RancherOS.
Key | Value | Default | Description
---|---|---| ---
`extra_args` | List of Strings | `[]` | Arbitrary daemon arguments, appended to the generated command
`environment` | List of Strings | `[]` |
`tls` | Boolean | `false` | When [setting up TLS]({{site.baseurl}}/os/configuration/setting-up-docker-tls/), this key needs to be set to true.
`tls_args` | List of Strings (used only if `tls: true`) | `[]` |
`server_key` | String (used only if `tls: true`)| `""` | PEM encoded server TLS key.
`server_cert` | String (used only if `tls: true`) | `""` | PEM encoded server TLS certificate.
`ca_key` | String (used only if `tls: true`) | `""` | PEM encoded CA TLS key.
`storage_context` | String | `console` | Specifies the name of the system container in whose context to run the Docker daemon process.
### Configuring System Docker
In your cloud-config, System Docker configuration is located under the `rancher.system_docker` key.
```yaml
#cloud-config
rancher:
system_docker:
storage_driver: overlay
```
#### Valid Keys for System Docker
All daemon arguments shown in the first table are also available to System Docker. The following are also supported.
Key | Value | Default | Description
---|---|---| ---
`extra_args` | List of Strings | `[]` | Arbitrary daemon arguments, appended to the generated command
`environment` | List of Strings (optional) | `[]` |

15
docs/os/configuration/hostname/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
title: Setting the Hostname in RancherOS
layout: os-default
---
## Setting the Hostname
---
You can set the hostname of the host using [cloud-config]({[site.baseurl}}/os/configuration/#cloud-config). The example below shows how to configure it.
```yaml
#cloud-config
hostname: myhost
```

83
docs/os/configuration/index.md Normal file
View File

@@ -0,0 +1,83 @@
---
title: Configuring RancherOS
layout: os-default
redirect_from:
- os/cloud-config/
---
## Configuring RancherOS
---
There are two ways that RancherOS can be configured.
1. A cloud-config file can be used to provide configuration when first booting RancherOS.
2. Manually changing configuration with the `ros config` command.
Typically, when you first boot the server, you pass in a cloud-config file to configure the initialization of the server. After the first boot, if you have any changes for the configuration, it's recommended that you use `ros config` to set the necessary configuration properties. Any changes will be saved on disk and a reboot will be required for changes to be applied.
### Cloud-Config
Cloud-config is a declarative configuration file format supported by many Linux distributions and is the primary configuration mechanism for RancherOS.
A Linux OS supporting cloud-config will invoke a cloud-init process during startup to parse the cloud-config file and configure the operating system. RancherOS runs its own cloud-init process in a system container. The cloud-init process will attempt to retrieve a cloud-config file from a variety of data sources. Once cloud-init obtains a cloud-config file, it configures the Linux OS according to the content of the cloud-config file.
When you create a RancherOS instance on AWS, for example, you can optionally provide cloud-config passed in the `user-data` field. Inside the RancherOS instance, cloud-init process will retrieve the cloud-config content through its AWS cloud-config data source, which simply extracts the content of user-data received by the VM instance. If the file starts with "`#cloud-config`", cloud-init will interpret that file as a cloud-config file. If the file starts with `#!<interpreter>` (e.g., `#!/bin/sh`), cloud-init will simply execute that file. You can place any configuration commands in the file as scripts.
A cloud-config file uses the YAML format. YAML is easy to understand and easy to parse. For more information on YAML, please read more at the [YAML site](http://www.yaml.org/start.html). The most important formatting principle is indentation or whitespace. This indentation indicates relationships of the items to one another. If something is indented more than the previous line, it is a sub-item of the top item that is less indented.
Example: Notice how both are indented underneath `ssh-authorized-keys`.
```yaml
#cloud-config
ssh_authorized_keys:
- ssh-rsa AAA...ZZZ example1@rancher
- ssh-rsa BBB...ZZZ example2@rancher
```
In our example above, we have our `#cloud-config` line to indicate it's a cloud-config file. We have 1 top-level property, `ssh_authorized_keys`. Its value is a list of public keys that are represented as a dashed list under `ssh_authorized_keys:`.
### Manually Changing Configuration
To update RancherOS configuration after booting, the `ros config` command can be used.
#### Getting Values
You can easily get any value that's been set in the `/var/lib/rancher/conf/cloud-config.yml` file. Let's see how easy it is to get the DNS configuration of the system.
```
$ sudo ros config get rancher.network.dns.nameservers
- 8.8.8.8
- 8.8.4.4
```
#### Setting Values
You can set values in the `/var/lib/rancher/conf/cloud-config.yml` file.
Setting a simple value in the `/var/lib/rancher/conf/cloud-config.yml`
```
$ sudo ros config set rancher.docker.tls true
```
Setting a list in the `/var/lib/rancher/conf/cloud-config.yml`
```
$ sudo ros config set rancher.network.dns.nameservers "['8.8.8.8','8.8.4.4']"
```
#### Exporting the Current Configuration
To output and review the current configuration state you can use the `ros config export` command.
```
$ sudo ros config export
rancher:
docker:
tls: true
network:
dns:
nameservers:
- 8.8.8.8
- 8.8.4.4
```

41
docs/os/configuration/kernel-modules-kernel-headers/index.md Normal file
View File

@@ -0,0 +1,41 @@
---
title: Installing Kernel Modules with Kernel Headers in RancherOS
layout: os-default
---
## Installing Kernel Modules that require Kernel Headers
To compile any kernel modules, you will need to download the kernel headers. The kernel headers are available in the form of a system service. Since the kernel headers are a system service, they need to be enabled using the `ros service` command.
### Installing Kernel Headers
The following commands can be used to install kernel headers for usage by containers in Docker or System Docker.
#### Docker
```
$ sudo ros service enable kernel-headers
$ sudo ros service up -d kernel-headers
```
#### System Docker
```
$ sudo ros service enable kernel-headers-system-docker
$ sudo ros service up -d kernel-headers-system-docker
```
The `ros service` commands will install the kernel headers in `/lib/modules/$(uname -r)/build`. Based on which service you install, the kernel headers will be available to containers, in Docker or System Docker, by bind mounting specific volumes. For any containers that compile a kernel module, the Docker command will need to bind mount in `/usr/src` and `/lib/modules`.
> **Note:** Since both commands install kernel headers in the same location, the only reason for different services is due to the fact that the storage places for System Docker and Docker are different. Either one or both kernel headers can be installed in the same RancherOS services.
### Example of Launching Containers to use Kernel Headers
```
# Run a container in Docker and bind mount specific directories
$ docker run -it -v /usr/src:/usr/src -v /lib/modules:/lib/modules ubuntu:15.10
# Run a container in System Docker and bind mount specific directories
$ sudo system-docker run -it -v /usr/src:/usr/src -v /lib/modules:/lib/modules ubuntu:15.10
```

20
docs/os/configuration/loading-kernel-modules/index.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Loading Kernel Modules in RancherOS
layout: os-default
---
## Loading Kernel Modules
---
Privileged containers can load kernel modules. In RancherOS, the kernel modules are in the standard `/lib/modules/$(uname -r)` folder. If you want to be able to run `modprobe` from a container, you will need to bind mount the `/lib/modules` into your container.
```yaml
myservice:
image: ...
privileged: true
volumes:
- /lib/modules:/lib/modules
```
By default, the `/lib/modules` folder is already available in the console.

22
docs/os/configuration/prepacking-docker-images/index.md Normal file
View File

@@ -0,0 +1,22 @@
---
title: Pre-packing Docker Images
layout: os-default
---
## Pre-packing Docker Images
---
On boot, RancherOS scans `/var/lib/rancher/preload/docker` and `/var/lib/rancher/preload/system-docker` directories and tries to load container image archives it finds there, with `docker load` and `system-docker load`.
The archives are `.tar` files, optionally compressed with `xz` or `gzip`. These can be produced by `docker save` command, e.g.:
```
$ docker save my-image1 my-image2 some-other/image3 | xz > my-images.tar.xz
```
The resulting files should be placed into `/var/lib/rancher/preload/docker` or `/var/lib/rancher/preload/system-docker` (depending on whether you want it preloaded into Docker or System Docker).
Pre-loading process only reads each new archive once, so it won't take time on subsequent boots (`<archive>.done` files are created to mark the read archives). If you update the archive (place a newer archive with the same name) it'll get read on the next boot as well.
Pre-packing docker images is handy when you're customizing your RancherOS distribution (perhaps, building cloud VM images for your infrastructure).

96
docs/os/configuration/private-registries/index.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Private Registries in RancherOS
layout: os-default
---
## Private Registries
---
When launching services through a [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), it is sometimes necessary to pull a private image from DockerHub or from a private registry. Authentication for these can be embedded in your cloud-config.
For example, to add authentication for DockerHub:
```yaml
#cloud-config
rancher:
registry_auths:
https://index.docker.io/v1/:
auth: dXNlcm5hbWU6cGFzc3dvcmQ=
```
The `auth` key is generated by base64 encoding a string of the form `username:password`. The `docker login` command can be be used to generate an `auth` key. After running the command and authenticating successfully, the key can be found in the `$HOME/.docker/config.json` file.
```json
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "dXNlcm5hbWU6cGFzc3dvcmQ="
}
}
}
```
Alternatively, a username and password can be specified directly.
```yaml
#cloud-config
rancher:
registry_auths:
https://index.docker.io/v1/:
username: username
password: password
```
### Docker Client Authentication
Configuring authentication for the Docker client is not handled by the `registry_auth` key. Instead, the `write_files` directive can be used to write credentials to the standard Docker configuration location.
```
#cloud-config
write_files:
- path: /home/rancher/.docker/config.json
permissions: "0755"
owner: rancher
content: |
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "asdf=",
"email": "not@val.id"
}
}
}
```
### Certificates for Private Registries
Certificates can be stored in the standard locations (i.e. `/etc/docker/certs.d`) following the [Docker documentation](https://docs.docker.com/registry/insecure). By using the `write_files` directive of the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), the certificates can be written directly into `/etc/docker/certs.d`.
```yaml
#cloud-config
write_files:
- path: /etc/docker/certs.d/myregistrydomain.com:5000/ca.crt
permissions: "0644"
owner: root
content: |
-----BEGIN CERTIFICATE-----
MIIDJjCCAg4CCQDLCSjwGXM72TANBgkqhkiG9w0BAQUFADBVMQswCQYDVQQGEwJB
VTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50ZXJuZXQgV2lkZ2l0
cyBQdHkgTHRkMQ4wDAYDVQQDEwVhbGVuYTAeFw0xNTA3MjMwMzUzMDdaFw0xNjA3
MjIwMzUzMDdaMFUxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEw
HwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQxDjAMBgNVBAMTBWFsZW5h
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxdVIDGlAySQmighbfNqb
TtqetENPXjNNq1JasIjGGZdOsmFvNciroNBgCps/HPJphICQwtHpNeKv4+ZuL0Yg
1FECgW7oo6DOET74swUywtq/2IOeik+i+7skmpu1o9uNC+Fo+twpgHnGAaGk8IFm
fP5gDgthrWBWlEPTPY1tmPjI2Hepu2hJ28SzdXi1CpjfFYOiWL8cUlvFBdyNqzqT
uo6M2QCgSX3E1kXLnipRT6jUh0HokhFK4htAQ3hTBmzcxRkgTVZ/D0hA5lAocMKX
EVP1Tlw0y1ext2ppS1NR9Sg46GP4+ATgT1m3ae7rWjQGuBEB6DyDgyxdEAvmAEH4
LQIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQA45V0bnGPhIIkb54Gzjt9jyPJxPVTW
mwTCP+0jtfLxAor5tFuCERVs8+cLw1wASfu4vH/yHJ/N/CW92yYmtqoGLuTsywJt
u1+amECJaLyq0pZ5EjHqLjeys9yW728IifDxbQDX0cj7bBjYYzzUXp0DB/dtWb/U
KdBmT1zYeKWmSxkXDFFSpL/SGKoqx3YLTdcIbgNHwKNMfTgD+wTZ/fvk0CLxye4P
n/1ZWdSeZPAgjkha5MTUw3o1hjo/0H0ekI4erZFrZnG2N3lDaqDPR8djR+x7Gv6E
vloANkUoc1pvzvxKoz2HIHUKf+xFT50xppx6wsQZ01pNMSNF0qgc1vvH
-----END CERTIFICATE-----
```

18
docs/os/configuration/resizing-device-partition/index.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: Resizing a Device Partition in RancherOS
layout: os-default
---
## Resizing a Device Partition
---
The `resize_device` cloud config option can be used to automatically extend the first partition to fill the size of it's device.
```yaml
#cloud-config
rancher:
resize_device: /dev/sda
```
This behavior is the default when launching RancherOS on AWS.

37
docs/os/configuration/running-commands/index.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Running Commands in RancherOS
layout: os-default
---
## Running Commands
---
You can automate running commands on boot using the `runcmd` cloud-config directive. Commands must be specified in a list syntax as in the following example.
```yaml
#cloud-config
runcmd:
- [ touch, /home/rancher/test ]
```
Commands specified using `runcmd` will be executed within the context of the `console` container. More details on the ordering of commands run in the `console` container can be found [here]({{site.baseurl}}/os/system-services/built-in-system-services/#console).
### Running Docker commands
When using `runcmd`, RancherOS will wait for all commands to complete before starting Docker. As a result, any `docker run` command should not be placed under `runcmd`. Instead, the `/etc/rc.local` script can be used. RancherOS will not wait for commands in this script to complete, so you can use the `wait-for-docker` command to ensure that the Docker daemon is running before performing any `docker run` commands.
```
#cloud-config
rancher:
write_files:
- path: /etc/rc.local
permissions: "0755"
owner: root
content: |
#!/bin/bash
wait-for-docker
docker run -d nginx
```
Running Docker commands in this manner is useful when pieces of the `docker run` command are dynamically generated. For services whose configuration is static, [adding a system service]({{site.baseurl}}/os/system-services/adding-system-services/) is recommended.

59
docs/os/configuration/setting-up-docker-tls/index.md Normal file
View File

@@ -0,0 +1,59 @@
---
title: Configuring TLS in RancherOS
layout: os-default
---
## Setting up Docker TLS
`ros tls generate` is used to generate both the client and server TLS certificates for Docker.
Remember, all `ros` commands need to be used with `sudo` or as a `root` user.
### End to end example
#### Enable TLS for Docker and Generate Server Certificate
To have docker secured by TLS you need to set `rancher.docker.tls` to `true`, and generate a set of server and client keys and certificates:
```
$ sudo ros config set rancher.docker.tls true
$ sudo ros tls gen --server -H localhost -H <hostname1> -H <hostname2> ... -H <hostnameN>
$ sudo system-docker restart docker
```
Here, `<hostname*>`s are the hostnames that you will be able to use as your docker host names. A `<hostname*>` can be a wildcard pattern, e.g. "`*.*.*.*.*`". It is recommended to have `localhost` as one of the hostnames, so that you can test docker TLS connectivity locally.
When you've done that, all the necessary server certificate and key files have been saved to `/etc/docker/tls` directory, and the `docker` service has been started with `--tlsverify` option.
#### Generate Client Certificates
You also need client cert and key to access Docker via a TCP socket now:
```
$ sudo ros tls gen
INFO[0000] Out directory (-d, --dir) not specified, using default: /home/rancher/.docker
```
All the docker client TLS files are in `~/.docker` dir now.
#### Test docker TLS connection
Now you can use your client cert to check if you can access Docker via TCP:
```
$ docker --tlsverify version
```
Because all the necessary files are in the `~/.docker` dir, you don't need to specify them using `--tlscacert` `--tlscert` and `--tlskey` options. You also don't need `-H` to access Docker on localhost.
Copy the files from `/home/rancher/.docker` to `$HOME/.docker` on your client machine if you need to access Docker on your RancherOS host from there.
On your client machine, set the Docker host and test out if Docker commands work.
```
$ export DOCKER_HOST=tcp://<hostname>:2376 DOCKER_TLS_VERIFY=1
$ docker ps
```

24
docs/os/configuration/ssh-keys/index.md Normal file
View File

@@ -0,0 +1,24 @@
---
title: SSH Keys in RancherOS
layout: os-default
---
## SSH Keys
---
RancherOS supports adding SSH keys through the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file. Within the cloud-config file, you simply add the ssh keys within the `ssh-authorized-keys` key.
```yaml
#cloud-config
ssh_authorized_keys:
- ssh-rsa AAA...ZZZ example1@rancher
- ssh-rsa BBB...ZZZ example2@rancher
```
When we pass the cloud-config file during the `ros install` command, it will allow these ssh keys to be associated with the **rancher** user. You can ssh into RancherOS using the key.
```
$ ssh -i /path/to/private/key rancher@<ip-address>
```

78
docs/os/configuration/switching-docker-versions/index.md Normal file
View File

@@ -0,0 +1,78 @@
---
title: Changing Docker Versions in RancherOS
layout: os-default
redirect_from:
- os/configuration/custom-docker/
---
## Changing Docker Versions
The version of User Docker used in RancherOS can be configured using a [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file or by using the `ros engine` command.
> **Note:** There are known issues in Docker when switching between versions. For production systems, we recommend setting the Docker engine only once [using a cloud-config](#setting-the-docker-engine-using-cloud-config).
### Available Docker engines
The `ros engine list` command can be used to show which Docker engines are available to switch to. This command will also provide details of which Docker engine is currently being used.
```
$ sudo ros engine list
disabled docker-1.10.3
disabled docker-1.11.2
current docker-1.12.1
```
### Setting the Docker engine using cloud-config
RancherOS supports defining which Docker engine to use through the cloud-config file. To change the Docker version from the default packaged version, you can use the following cloud-config setting and select one of the available engines. In the following example, we'll use the cloud-config file to set RancherOS to use Docker 1.10.3 for User Docker.
```yaml
#cloud-config
rancher:
docker:
engine: docker-1.10.3
```
### Changing Docker engines after RancherOS has started
If you've already started RancherOS and want to switch Docker engines, you can change the Docker engine by using the `ros engine switch` command. In our example, we'll switch to Docker 1.11.2.
```
$ sudo ros engine switch docker-1.11.2
INFO[0000] Project [os]: Starting project
INFO[0000] [0/19] [docker]: Starting
Pulling docker (rancher/os-docker:1.11.2)...
1.11.2: Pulling from rancher/os-docker
2a6bbb293656: Pull complete
Digest: sha256:ec57fb24f6d4856d737e14c81a20f303afbeef11fc896d31b4e498829f5d18b2
Status: Downloaded newer image for rancher/os-docker:1.11.2
INFO[0007] Recreating docker
INFO[0007] [1/19] [docker]: Started
INFO[0007] Project [os]: Project started
$ docker version
Client:
Version: 1.11.2
API version: 1.23
Go version: go1.5.4
Git commit: b9f10c9
Built: Wed Jun 1 21:20:08 2016
OS/Arch: linux/amd64
Server:
Version: 1.11.2
API version: 1.23
Go version: go1.5.4
Git commit: b9f10c9
Built: Wed Jun 1 21:20:08 2016
OS/Arch: linux/amd64
```
### Enabling Docker engines
If you don't want to automatically switch Docker engines, you can also set which version of Docker to use after the next reboot by enabling a Docker engine.
```
$ sudo ros engine enable docker-1.10.3
```

17
docs/os/configuration/sysctl/index.md Normal file
View File

@@ -0,0 +1,17 @@
---
title: sysctl Settings in RancherOS
layout: os-default
---
## sysctl Settings
---
The `rancher.sysctl` cloud-config key can be used to control sysctl parameters. This works in a manner similar to `/etc/sysctl.conf` for other Linux distros.
```
#cloud-config
rancher:
sysctl:
net.ipv4.conf.default.rp_filter: 1
```

15
docs/os/configuration/users/index.md Normal file
View File

@@ -0,0 +1,15 @@
---
title: Users in RancherOS
layout: os-default
---
## Configuring RancherOS Users
---
Currently, we don't support adding other users besides `rancher`.
You _can_ add users in the console container, but these users will only exist as long as the console container exists. It only makes sense to add users in a [persistent consoles]({{site.baseurl}}/os/configuration/custom-console/#console-persistence).
If you want the console user to be able to ssh into RancherOS, you need to add them
to the `docker` group.

46
docs/os/configuration/write-files/index.md Normal file
View File

@@ -0,0 +1,46 @@
---
title: Writing Files in RancherOS
layout: os-default
---
## Writing Files
---
You can automate writing files to disk using the `write_files` cloud-config directive.
```yaml
#cloud-config
write_files:
- path: /etc/rc.local
permissions: "0755"
owner: root
content: |
#!/bin/bash
echo "I'm doing things on start"
```
### Writing Files in Specific System Services
By default, the `write_files` directive will create files in the console container. To write files in other system services, the `container` key can be used. For example, the `container` key could be used to write to `/etc/ntp.conf` in the NTP system service.
```yaml
#cloud-config
write_files:
- container: ntp
path: /etc/ntp.conf
permissions: "0644"
owner: root
content: |
server 0.pool.ntp.org iburst
server 1.pool.ntp.org iburst
server 2.pool.ntp.org iburst
server 3.pool.ntp.org iburst
# Allow only time queries, at a limited rate, sending KoD when in excess.
# Allow all local queries (IPv4, IPv6)
restrict default nomodify nopeer noquery limited kod
restrict 127.0.0.1
restrict [::1]
```

70
docs/os/contributing/index.md Normal file
View File

@@ -0,0 +1,70 @@
---
title: Contributing to RancherOS
layout: os-default
---
## Contributing to RancherOS
---
## Developing
Development is easiest done with QEMU on Linux. OS X works too, although QEMU doesn't have KVM support. If you are running Linux in a virtual machine, then we recommend you run VMWare Fusion/Workstation and enable VT-x support. Then, QEMU will have KVM support and run sufficiently fast inside your Linux VM.
### Building
#### Requirements:
* bash
* make
* Docker 1.10.3+
```
$ make
```
The build will run in Docker containers, and when the build is done, the vmlinuz, initrd, and ISO should be in `dist/artifacts`.
If you're building a version of RancherOS used for development and not for a release, you can instead run `make dev`. This will run faster than the standard build by avoiding building the `installer.tar` and `rootfs.tar.gz` artifacts which are not needed by QEMU.
### Testing
Run `make integration-tests` to run the all integration tests in a container, or `./scripts/integration-tests` to run them outside a container (they use QEMU to test the OS.)
### Running
Prerequisites: QEMU, coreutils, cdrtools/genisoimage/mkisofs.
On OS X, `brew` is recommended to install those. On Linux, use your distro package manager.
To launch RancherOS in QEMU from your dev version, you can either use `make run`, or customise the vm using `./scripts/run` and its options. You can use `--append your.kernel=params here` and `--cloud-config your-cloud-config.yml` to configure the RancherOS instance you're launching.
You can SSH in using `./scripts/ssh`. Your SSH keys should have been populated (if you didn't provide your own cloud-config) so you won't need a password. If you don't have SSH keys, or something is wrong with your cloud-config, then the password is "`rancher`".
If you're on OS X, you can run RancherOS using [_xhyve_](https://github.com/mist64/xhyve) instead of QEMU: just pass `--xhyve` to `./scripts/run` and `./scripts/ssh`.
### Debugging and logging.
You can enable extra log information by setting them using `sudo ros config set`,
or as kernel boot parameters.
Enable all logging by setting `rancher.debug` true
or you can set `rancher.docker.debug`, `racher.system_docker.debug`, `rancher.bootstrap_docker.debug`, or `rancher.log` individually.
## Repositories
All of repositories are located within our main GitHub [page](https://github.com/rancher).
[RancherOS Repo](https://github.com/rancher/os): This repo contains the bulk of the RancherOS code.
[RancherOS Services Repo](https://github.com/rancher/os-services): This repo is where any [system-services]({{site.baseurl}}/os/system-services/) can be contributed.
[RancherOS Images Repo](https://github.com/rancher/os-images): This repo is for the corresponding service images.
## Bugs
If you find any bugs or are having any trouble, please contact us by filing an [issue](https://github.com/rancher/os/issues/new).
If you have any updates to our documentation, please make any PRs to our [docs repo](https://github.com/rancher/rancher.github.io).
<br>
<br>

18
docs/os/faqs/amazon/index.md Normal file
View File

@@ -0,0 +1,18 @@
---
title: Amazon FAQs
layout: os-default
---
## Amazon Frequently Asked Questions
---
### How can I extend my disk size?
Assuming your EC2 instance with RancherOS with more disk space than what's being read, run the following command to extend the disk size. This allows RancherOS to see the disk size.
```
$ docker run --privileged --rm --it debian:jessie resize2fs /dev/xvda1
```
`xvda1` should be the right disk for your own setup. In the future, we will be trying to create a system service that would automatically do this on boot in AWS.

23
docs/os/faqs/index.md Normal file
View File

@@ -0,0 +1,23 @@
---
title: FAQs
layout: os-default
---
## Frequently Asked Questions
---
###What is required to run RancherOS?
RancherOS runs on any laptop, physical, or virtual servers.
###What are some commands?
Command | Description
--------|------------
`docker`| Good old Docker, use that to run stuff.
`system-docker` | The Docker instance running the system containers. Must run as root or using `sudo`
`ros` | Control and configure RancherOS

45
docs/os/index.md Normal file
View File

@@ -0,0 +1,45 @@
---
title: Overview of RancherOS
layout: os-default
---
## Overview of RancherOS
---
RancherOS is the smallest, easiest way to run Docker in production. Everything in RancherOS is a container managed by Docker. This includes system services such as `udev` and `syslog`. RancherOS is dramatically smaller than most traditional operating systems, because it only includes the services necessary to run Docker. By removing unnecessary libraries and services, requirements for security patches and other maintenance are dramatically reduced. This is possible because with Docker, users typically package all necessary libraries into their containers.
Another way in which RancherOS is designed specifically for running Docker is that it always runs the latest version of Docker. This allows users to take advantage of the latest Docker capabilities and bug fixes.
Like other minimalist Linux distributions, RancherOS boots incredibly quickly, generally in 5-10 seconds. Starting Docker containers is nearly instant, similar to starting any other process. This quickness is ideal for organizations adopting microservices and autoscaling.
Docker is an open-source platform designed for developers, system admins, and DevOps, it is used to build, ship, and run containers, using simple yet powerful CLI (Command Line Interface), you can get started with Docker from [Docker user guide](https://docs.docker.com/userguide/).
### Hardware Requirements
---
* x86_64 server with at least 512MB of RAM.
> **Note:** If you are planning on [installing to disk]({{site.baseurl}}/os/running-rancheros/server/install-to-disk/), you will need at least 1024MB of RAM.
### How this works
---
Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker**, the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd`, and can be used to launch [additional system services]({{site.baseurl}}/os/system-services/adding-system-services/).
System Docker runs a special container called **Docker**, which is another Docker daemon responsible for managing all of the user’s containers. Any containers that you launch as a user from the console will run inside this Docker. This creates isolation from the System Docker containers, and ensures normal user commands don’t impact system services.
We created this separation because it seemed logical and also it would really be bad if somebody did
`docker rm -f $(docker ps -qa)` and deleted the entire OS.
![How it works]({{site.baseurl}}/img/os/rancheroshowitworks.png "How it works")
### Running RancherOS
---
To find out more about installing RancherOS, jump to our [Quick Start Guide]({{site.baseurl}}/os/quick-start-guide/).
### Latest Release
---
Please check our repository for the latest release in our [README](https://github.com/rancher/os/blob/master/README.md).
<br>
<br>

31
docs/os/networking/dns/index.md Normal file
View File

@@ -0,0 +1,31 @@
---
title: Configuring DNS in RancherOS
layout: os-default
redirect_from:
- os/configuration/networking/#dns
---
## DNS
If you wanted to configure the DNS through the cloud config file, you'll need to place DNS configurations within the `rancher` key.
```yaml
#cloud-config
#Remember, any changes for rancher will be within the rancher key
rancher:
network:
dns:
search:
- mydomain.com
- example.com
```
Using `ros config`, you can set the `nameservers`, and `search`, which directly map to the fields of the same name in `/etc/resolv.conf`.
```
$ sudo ros config set rancher.network.dns.search "['mydomain.com','example.com']"
$ sudo ros config get rancher.network.dns.search
- mydomain.com
- example.com
```

96
docs/os/networking/interfaces/index.md Normal file
View File

@@ -0,0 +1,96 @@
---
title: Configuring Network Interfaces in RancherOS
layout: os-default
redirect_from:
- os/configuration/networking/
---
## Interfaces
Using `ros config`, you can configure specific interfaces. Wildcard globbing is supported so `eth*` will match `eth1` and `eth2`. The available options you can configure are `address`, `gateway`, `mtu`, and `dhcp`.
```
$ sudo ros config set rancher.network.interfaces.eth1.address 172.68.1.100/24
$ sudo ros config set rancher.network.interfaces.eth1.gateway 172.68.1.1
$ sudo ros config set rancher.network.interfaces.eth1.mtu 1500
$ sudo ros config set rancher.network.interfaces.eth1.dhcp false
```
If you wanted to configure the interfaces through the cloud config file, you'll need to place interface configurations within the `rancher` key.
```yaml
#cloud-config
rancher:
network:
interfaces:
eth1:
address: 172.68.1.100/24
gateway: 172.68.1.1
mtu: 1500
dhcp: false
```
### Multiple NICs
If you want to configure one of multiple network interfaces, you can specify the MAC address of the interface you want to configure.
Using `ros config`, you can specify the MAC address of the NIC you want to configure as follows:
```
$ sudo ros config set rancher.network.interfaces.”mac=ea:34:71:66:90:12:01”.dhcp true
```
Alternatively, you can place the MAC address selection in your cloud config file as follows:
```yaml
#cloud-config
rancher:
network:
interfaces:
"mac=ea:34:71:66:90:12:01":
dhcp: true
```
### NIC bonding
You can aggregate several network links into one virtual link for redundancy and increased throughput. For example:
```yaml
#cloud-config
rancher:
network:
interfaces:
bond0:
addresses:
- 192.168.101.33/31
- 10.88.23.129/31
gateway: 192.168.101.32
bond_opts:
downdelay: "200"
lacp_rate: "1"
miimon: "100"
mode: "4"
updelay: "200"
xmit_hash_policy: layer3+4
post_up:
- ip route add 10.0.0.0/8 via 10.88.23.128
mac=0c:c4:d7:b2:14:d2:
bond: bond0
mac=0c:c4:d7:b2:14:d3:
bond: bond0
```
In this example two physical NICs (with MACs `0c:c4:d7:b2:14:d2` and `0c:c4:d7:b2:14:d3`) are aggregated into a virtual one `bond0`.
### VLANS
In this example, you can create an interface `eth0.100` which is tied to VLAN 100 and an interface `foobar` that will be tied to VLAN 200.
```
#cloud-config
rancher:
network:
interfaces:
eth0:
vlans: 100,200:foobar
```

36
docs/os/networking/proxy-settings/index.md Normal file
View File

@@ -0,0 +1,36 @@
---
title: Configuring Proxy Settings in RancherOS
layout: os-default
---
## Proxy settings
HTTP proxy settings can be set directly under the `network` key. This will automatically configure proxy settings for both Docker and System Docker.
```yaml
#cloud-config
rancher:
network:
http_proxy: https://myproxy.example.com
https_proxy: https://myproxy.example.com
no_proxy: localhost,127.0.0.1
```
<br>
> **Note:** System Docker proxy settings will not be applied until after a reboot.
To add the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables to a system service, specify each under the `environment` key for the service.
```yaml
#cloud-config
rancher:
services:
myservice:
...
environment:
- HTTP_PROXY
- HTTPS_PROXY
- NO_PROXY
```

134
docs/os/quick-start-guide/index.md Normal file
View File

@@ -0,0 +1,134 @@
---
title: Quick Start Guide for RancherOS
layout: os-default
---
## Quick Start Guide
---
If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{site.baseurl}}/os/running-rancheros/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{site.baseurl}}/os/running-rancheros/workstation/docker-machine/) and show you some of what RancherOS can do.
### Launching RancherOS using Docker Machine
Before moving forward, you'll need to have [Docker Machine](https://docs.docker.com/machine/) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) installed. Once you have VirtualBox and Docker Machine installed, it's just one command to get RancherOS running.
```
$ docker-machine create -d virtualbox --virtualbox-boot2docker-url https://releases.rancher.com/os/latest/rancheros.iso <MACHINE-NAME>
```
That's it! You're up and running a RancherOS instance.
To log into the instance, just use the `docker-machine` command.
```
$ docker-machine ssh <MACHINE-NAME>
```
### A First Look At RancherOS
There are two Docker daemons running in RancherOS. The first is called **System Docker**, which is where RancherOS runs system services like ntpd and syslog. You can use the `system-docker` command to control the **System Docker** daemon.
The other Docker daemon running on the system is **Docker**, which can be accessed by using the normal `docker` command.
When you first launch RancherOS, there are no containers running in the Docker daemon. However, if you run the same command against the System Docker, you’ll see a number of system services that are shipped with RancherOS.
> **Note:** `system-docker` can only be used by root, so it is necessary to use the `sudo` command whenever you want to interact with System Docker.
```
$ sudo system-docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6f56057cf5ba rancher/os-base:v0.5.0 "/usr/sbin/entry.sh /" 16 seconds ago Up 15 seconds docker
bd5376830237 rancher/os-console:v0.5.0 "/usr/sbin/entry.sh /" 16 seconds ago Up 15 seconds console
ede8ce39fff5 rancher/os-base:v0.5.0 "/usr/sbin/entry.sh n" 16 seconds ago Up 15 seconds network
9e5d18bca391 rancher/os-base:v0.5.0 "/usr/sbin/entry.sh n" 17 seconds ago Up 16 seconds ntp
393b9fb7e30a rancher/os-udev:v0.5.0 "/usr/sbin/entry.sh /" 18 seconds ago Up 16 seconds udev
dc2cafca3c69 rancher/os-syslog:v0.5.0 "/usr/sbin/entry.sh /" 18 seconds ago Up 17 seconds syslog
439d5535fbfa rancher/os-base:v0.5.0 "/usr/sbin/entry.sh /" 18 seconds ago Up 17 seconds acpid
```
Some containers are run at boot time, and others, such as the `console`, `docker`, etc. containers are always running.
## Using RancherOS
---
### Deploying a Docker Container
Let's try to deploy a normal Docker container on the Docker daemon. The RancherOS Docker daemon is identical to any other Docker environment, so all normal Docker commands work.
```
$ docker run -d nginx
```
You can see that the nginx container is up and running:
```
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
e99c2c4b8b30 nginx "nginx -g 'daemon off" 12 seconds ago Up 11 seconds 80/tcp, 443/tcp drunk_ptolemy
```
### Deploying A System Service Container
The following is a simple Docker container to set up Linux-dash, which is a minimal low-overhead web dashboard for monitoring Linux servers. The Dockerfile will be like this:
```
FROM hwestphal/nodebox
MAINTAINER hussein.galal.ahmed.11@gmail.com
RUN opkg-install unzip
RUN curl -k -L -o master.zip https://github.com/afaqurk/linux-dash/archive/master.zip
RUN unzip master.zip
WORKDIR linux-dash-master
RUN npm install
ENTRYPOINT ["node","server"]
```
Using the `hwestphal/nodebox` image, which uses a Busybox image and installs `node.js` and `npm`. We downloaded the source code of Linux-dash, and then ran the server. Linux-dash will run on port 80 by default.
To run this container in System Docker use the following command:
```
$ sudo system-docker run -d --net=host --name busydash husseingalal/busydash
```
In the commad, we used `--net=host` to tell System Docker not to containerize the container's networking, and use the host’s networking instead. After running the container, you can see the monitoring server by accessing `http://<IP_OF_MACHINE`.
![System Docker Container]({{site.baseurl}}/img/os/Rancher_busydash.png)
To make the container survive during the reboots, you can create the `/opt/rancher/bin/start.sh` script, and add the Docker start line to launch the Docker at each startup.
```
$ sudo mkdir -p /opt/rancher/bin
$ echo “sudo system-docker start busydash” | sudo tee -a /opt/rancher/bin/start.sh
$ sudo chmod 755 /opt/rancher/bin/start.sh
```
### Using ROS
Another useful command that can be used with RancherOS is `ros` which can be used to control and configure the system.
```
$ ros -v
ros version 0.0.1
```
RancherOS state is controlled by a cloud config file. `ros` is used to edit the configuration of the system, to see for example the dns configuration of the system:
```
$ sudo ros config get rancher.dns
- 8.8.8.8
- 8.8.4.4
```
When using the native Busybox console, any changes to the console will be lost after reboots, only changes to `/home` or `/opt` will be persistent. You can use the `ros console switch` command to switch to a [persistent console]({{site.baseurl}}/os/configuration/custom-console/#console-persistence) and replace the native Busybox console. For example, to switch to the Ubuntu console:
```
$ sudo ros console switch ubuntu
```
### Conclusion
RancherOS is a simple Linux distribution ideal for running Docker. By embracing containerization of system services and leveraging Docker for management, RancherOS hopes to provide a very reliable, and easy to manage OS for running containers.

102
docs/os/running-rancher-on-rancheros/index.md Normal file
View File

@@ -0,0 +1,102 @@
---
title: Running Rancher on RancherOS
layout: os-default
---
## Tips on using Rancher with RancherOS
---
RancherOS can be used to launch [Rancher]({{site.baseurl}}/rancher/) and be used as the OS to [add hosts]({{site.baseurl}}/rancher/rancher-ui/infrastructure/hosts/custom) to Rancher.
### Launching Agents using Cloud-Config
You can easily add hosts into Rancher by using [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) to launch the rancher/agent container.
After Rancher is launched and [host registration]({{site.baseurl}}/rancher/configuration/settings/#host-registration) has been saved, you will be able to find the [custom command]({{site.baseurl}}/rancher/rancher-ui/infrastructure/hosts/custom) in the **Infrastructure** -> **Hosts** -> **Custom** page.
```bash
$ sudo docker run --d --privileged -v /var/run/docker.sock:/var/run/docker.sock \
rancher/agent:v0.8.2 http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
```
<br>
> **Note:** The `rancher/agent` version is correlated to the Rancher server version. You will need to check the custom command to get the appropriate tag for the version to use.
_Cloud-Config Example_
Here's using the command above and converting it into a cloud-config file to launch the rancher/agent in docker when RancherOS boots up.
```yaml
#cloud-config
rancher:
services:
rancher-agent1:
image: rancher/agent:v0.8.2
command: http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
privileged: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
```
<br>
> **Note:** You can not name the service `rancher-agent` as this will not allow the rancher/agent container to be launched correctly. Please read more about why [you can't name your container as `rancher-agent`]({{site.baseurl}}/rancher/faqs/agents/#adding-in-name-rancher-agent).
### Adding in Host Labels
With each host, you have the ability to add labels to help you organize your hosts. The labels are added as an environment variable when launching the rancher/agent container. The host label in the UI will be a key/value pair and the keys must be unique identifiers. If you added two keys with different values, we'll take the last inputted value to use as the key/value pair.
By adding labels to hosts, you can use these labels when [schedule services/load balancers/services]({{site.baseurl}}/rancher/rancher-ui/scheduling/) and create a whitelist or blacklist of hosts for your [services]({{site.baseurl}}/rancher/rancher-ui/applications/stacks/adding-services/) to run on.
When adding a custom host, you can add the labels using the UI and it will automatically add the environment variable (`CATTLE_HOST_LABELS`) with the key/value pair into the command on the UI screen.
#### Native Docker Commands Example
```bash
# Adding one host label to the rancher/agent command
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar' -d --privileged \
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \
http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
# Adding more than one host label requires joining the additional host labels with an `&`
$ sudo docker run -e CATTLE_HOST_LABELS='foo=bar&hello=world' -d --privileged \
-v /var/run/docker.sock:/var/run/docker.sock rancher/agent:v0.8.2 \
http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
```
#### Cloud-Config Example
Adding one host label
```yaml
#cloud-config
rancher:
services:
rancher-agent1:
image: rancher/agent:v0.8.2
command: http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
privileged: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
CATTLE_HOST_LABELS: foo=bar
```
<br>
Adding more than one host label requires joining the additional host labels with an `&`
```yaml
#cloud-config
rancher:
services:
rancher-agent1:
image: rancher/agent:v0.8.2
command: http://<rancher-server-ip>:8080/v1/projects/1a5/scripts/<registrationToken>
privileged: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
CATTLE_HOST_LABELS: foo=bar&hello=world
```

76
docs/os/running-rancheros/cloud/aws/index.md Normal file
View File

@@ -0,0 +1,76 @@
---
title: Getting Started on Amazon EC2
layout: os-default
---
## Running RancherOS on AWS
----
RancherOS is available as an Amazon Web Services AMI, and can be easily run on EC2. You can launch RancherOS either using the AWS Command Line Interface (CLI) or using the AWS console.
### Launching RancherOS through the AWS CLI
If you haven't installed the AWS CLI, follow the instructions on the [AWS CLI page](http://aws.amazon.com/cli/) to install the CLI and configure access key and secret keys.
Once you've installed your AWS CLI, use this command to launch an EC2 instance with the RancherOS AMI. You will need to know your SSH key name and security group name for the _region_ that you are configured for. These can be found from the AWS console.
> **Note:** Check the RancherOS [README](https://github.com/rancher/os/blob/master/README.md) for AMI names for each region. We support PV and HVM types of AMIs.
```
$ aws ec2 run-instances --image-id ami-ID# --count 1 --instance-type t2.micro --key-name MySSHKeyName --security-groups sg-name
```
Your EC2 instance is now running RancherOS!
### Launching RancherOS through the AWS Console
Let’s walk through how to import and create a RancherOS on EC2 machine using the AWS console.
1. First login to your AWS console, and go to the EC2 dashboard, click on **Launch Instance**:
![RancherOS on AWS 1]({{site.baseurl}}/img/os/Rancher_aws1.png)
2. Select the **Community AMIs** on the sidebar and search for **RancherOS**. Pick the latest version and click **Select**.
![RancherOS on AWS 2]({{site.baseurl}}/img/os/Rancher_aws2.png)
3. Go through the steps of creating the instance type through the AWS console. If you want to pass in a [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file during boot of RancherOS, you'd pass in the file as **User data** by expanding the **Advanced Details** in **Step 3: Configure Instance Details**. You can pass in the data as text or as a file.
![RancherOS on AWS 6]({{site.baseurl}}/img/os/Rancher_aws6.png)
After going through all the steps, you finally click on **Launch**, and either create a new key pair or choose an existing key pair to be used with the EC2 instance. If you have created a new key pair, download the key pair. If you have chosen an existing key pair, make sure you have the key pair accessible. Click on **Launch Instances**.
![RancherOS on AWS 3]({{site.baseurl}}/img/os/Rancher_aws3.png)
4. Your instance will be launching and you can click on **View Instances** to see it's status.
![RancherOS on AWS 4]({{site.baseurl}}/img/os/Rancher_aws4.png)
Your instance is now running!
![RancherOS on AWS 5]({{site.baseurl}}/img/os/Rancher_aws5.png)
## Logging into RancherOS
----
From a command line, log into the EC2 Instance. If you added ssh keys using a cloud-config,
both those keys, and the one you selected in the AWS UI will be installed.
```
$ ssh -i /Directory/of/MySSHKeyName.pem rancher@<ip-of-ec2-instance>
```
If you have issues logging into RancherOS, try using this command to help debug the issue.
```
$ ssh -v -i /Directory/of/MySSHKeyName.pem rancher@<ip-of-ec2-instance>
```
## Latest AMI Releases
----
Please check the [README](https://github.com/rancher/os/blob/master/README.md) in our RancherOS repository for our latest AMIs.

32
docs/os/running-rancheros/cloud/azure/index.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: Running RancherOS on Azure
layout: os-default
---
## Running RancherOS on Azure
---
RancherOS is available as an image with Azure Resource Management. Please note that RancherOS is only offered in Azure Resource Management and not available in the Azure Service Management.
> **Note:** Currently, we only have v0.3.1 available as an image in Azure and it does not support passing in cloud config files. We are working on adding a new version that has cloud config enabled. Also, only certain regions are supported with RancherOS on Azure.
### Launching Rancheros through the Azure Portal
Using the new Azure Resource Management portal, click on **Marketplace**. Search for **RancherOS**. Click on **Create**.
Follow the steps to create a virtual machine.
In the _Basics_ step, provide a **name** for the VM, use _rancher_ as the **user name** and select the **SSH public key** option of authenticating. Add your ssh public key into the appropriate field. Select the **Resource group** that you want to add the VM to or create a new one. Select the **location** for your VM.
In the _Size_ step, select a virtual machine that has at least **1GB** of memory.
In the _Settings_ step, you can use all the default settings to get RancherOS running.
Review your VM and buy it so that you can **Create** your VM.
After the VM has been provisioned, click on the VM to find the public IP address. SSH into your VM using the _rancher_ username.
```
$ ssh rancher@<public_ip_of_vm> -p 22
```

10
docs/os/running-rancheros/cloud/do/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Running RancherOS on Digital Ocean
layout: os-default
---
## Running RancherOS on DigitalOcean
---
Running RancherOS on DigitalOcean is not yet supported.

148
docs/os/running-rancheros/cloud/gce/index.md Normal file
View File

@@ -0,0 +1,148 @@
---
title: Running RancherOS on GCE
layout: os-default
---
## Running RancherOS on Google Compute Engine (GCE)
----
Note: The Google Compute Engine image is still experimental. There are known issues with the image, so please do not use it in production!
### Adding the RancherOS Image into GCE
RancherOS is available as an image in GCE, and can be easily run in Google Compute Engine (GCE). Let’s walk through how to upload GCE image.
1. Download the most recent RancherOS image. The image can be found in the [release artifacts](https://github.com/rancher/os/releases). It is a `.tar.gz` file.
2. Follow Google's instructions on how to [upload the image](https://cloud.google.com/compute/docs/tutorials/building-images#publishingimage). The image must be uploaded into a Google Cloud Storage bucket before it can be added to a project.
3. Follow Google's instructions on how to [import a RAW image](https://cloud.google.com/compute/docs/images/import-existing-image#use_saved_image).
4. Once the image is added to your Google Compute Engine, we can start creating new instances!
### Launching RancherOS using `gcloud compute`
After the image is uploaded, we can use the `gcloud compute` [command-line tool](https://cloud.google.com/compute/docs/gcloud-compute/) to start a new instance. It automatically merges the SSH keys from the project and adds the keys to the **rancher** user. If you don't have any project level SSH keys, go to the _Adding SSH Keys_ section to learn more about adding SSH keys.
Since the image is private, we need to follow Google's [instructions](https://cloud.google.com/compute/docs/creating-custom-image#start_an_instance_from_a_custom_image).
```
$ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_INSTANCE> <INSTANCE_NAME> --image <PRIVATE_IMAGE_NAME>
```
### Using a Cloud Config File with GCE
If you want to pass in your own cloud config file that will be processed by [cloud init]({{site.baseurl}}/os/configuration/#cloud-config), you can pass it as metadata upon creation of the instance during the `gcloud compute` command. The file will need to be stored locally before running the command. The key of the metadata will be `user-data` and the value is the location of the file. If any SSH keys are added in the cloud config file, it will also be added to the **rancher** user.
```
$ gcloud compute instances create --project <PROJECT_ID> --zone <ZONE_TO_CREATE_INSTANCE> <INSTANCE_NAME> --image <PRIVATE_IMAGE_NAME> --metadata-from-file user-data=/Directory/of/Cloud_Config.yml
```
**Adding your Cloud Config to Existing Instance**
If you have already created the instance, you can still add the cloud config file after the instance is created. You will just need to reset the machine after you've added the metadata.
```
$ gcloud compute instances add-metadata <INSTANCE_NAME> --metadata-from-file user-data=/Directory/of/File --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE>
Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF_INSTANCE/instances/INSTANCE_NAME].
$ gcloud compute instances reset <INSTANCE_NAME> --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE>
Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF_INSTANCE/instances/INSTANCE_NAME].
```
**Reviewing your Cloud Config**
If you want to review the cloud config file for your instance, review the **metadata** section:
```
$ gcloud compute instances describe <INSTANCE_NAME> --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE>
```
**Removing your Cloud Config**
If you want to remove your cloud config file, use the following command to remove the metadata.
```
$ gcloud compute instances remove-metadata <INSTANCE_NAME> --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE> --keys user-data
Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF_INSTANCE/instances/INSTANCE_NAME].
```
**Resetting your Instance**
After any changes to the cloud config file, you'll need to reset the machine. You can reset either using the console or using this command:
```
$ gcloud compute instances reset <INSTANCE_NAME> --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE>
Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF_INSTANCE/instances/INSTANCE_NAME].
```
### Launching RancherOS using the Google Console
After the image is uploaded, it's easy to use the console to create new instances. You will **not** be able to upload your own cloud config file when creating instances through the console. You can add it after the instance is created using `gcloud compute` commands and resetting the instance.
1. Make sure you are in the project that the image was created in.
![RancherOS on GCE 4]({{site.baseurl}}/img/os/Rancher_gce4.png)
2. In the navigation bar, click on the **VM instances**, which is located at Compute -> Compute Engine -> Metadata. Click on **Create instance**.
![RancherOS on GCE 5]({{site.baseurl}}/img/os/Rancher_gce5.png)
2. Fill out the information for your instance. In the **Image** dropdown, your private image will be listed among the public images provided by Google. Select the private image for RancherOS. Click **Create**.
![RancherOS on GCE 6]({{site.baseurl}}/img/os/Rancher_gce6.png)
3. Your instance is being created and will be up and running shortly!
#### Adding SSH keys
In order to SSH into the GCE instance, you will need to have SSH keys set up in either the project instance, add them to the instance after the instance is created, or add them using the `gcloud compute` commands to add meta-data to an instance.
**Option 1: Project Level SSH Keys**
In your project, click on **Metadata**, which is located within Compute -> Compute Engine -> Metadata. Click on **SSH Keys**.
![RancherOS on GCE 7]({{site.baseurl}}/img/os/Rancher_gce7.png)
Add the SSH keys that you want to have access to any instances within your project.
Note: If you do this after any RancherOS instance is created, you will need to reset the instance so that the SSH keys are added to the **rancher** user.
**Option 2: Instance Level SSH Keys**
After your instance is created, click on the instance name. Scroll down to the **SSH Keys** section and click on **Add SSH key**. This key will only be applicable to the instance.
![RancherOS on GCE 8]({{site.baseurl}}/img/os/Rancher_gce8.png)
After the SSH keys have been added, you'll need to reset the machine, by clicking **Reset**.
![RancherOS on GCE 9]({{site.baseurl}}/img/os/Rancher_gce9.png)
After a little bit, you will be able to SSH into the box using the **rancher** user.
**Option 3: Using the Cloud Config file**
You can add SSH keys by adding them into the cloud config file. Follow the directions above that walk through how to pass the cloud config file to an instance.
Example of cloud config file that has only SSH keys:
```yaml
#cloud-config
ssh_authorized_keys:
- ssh-rsa AAA... user@host
```
## Logging into RancherOS
----
Remember, the SSH keys are passed to the **rancher** user. The SSH keys can be passed from the project level, the instance level or through the cloud config file. If you add any of these SSH keys after the instance has been created, the instance will need to be reset before the SSH keys are passed through.
```
$ gcloud compute ssh rancher@<INSTANCE_NAME> --project <PROJECT_ID> --zone <ZONE_OF_INSTANCE>
```
If you have issues logging into RancherOS, try using this command to help debug the instance.
```
$ gcloud compute instances get-serial-port-output <INSTANCE_NAME> --zone <ZONE_OF_INSTANCE> --project <PROJECT_ID>
```

11
docs/os/running-rancheros/cloud/openstack/index.md Normal file
View File

@@ -0,0 +1,11 @@
---
title: Rancher RancherOS in Openstack
layout: os-default
---
## Openstack
---
As of v0.5.0, RancherOS releases include an Openstack image that can be found on our [releases page](https://github.com/rancher/os/releases). The image format is QCOW2.
When launching an instance using the image, you must enable **Advanced Options** -> **Configuration Drive** and in order to use a [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config) file.

39
docs/os/running-rancheros/index.md Normal file
View File

@@ -0,0 +1,39 @@
---
title: Running RancherOS
layout: os-default
---
## Running RancherOS
---
RancherOS runs on virtualization platforms, cloud providers and bare metal servers. We also support running a local VM on your laptop. To start running RancherOS as quickly as possible, follow our [Quick Start Guide]({{site.baseurl}}/os/quick-start-guide/).
### Platforms
#### Workstation
[Docker Machine]({{site.baseurl}}/os/running-rancheros/workstation/docker-machine)
[Boot from ISO]({{site.baseurl}}/os/running-rancheros/workstation/boot-from-iso)
#### Cloud
[Amazon EC2]({{site.baseurl}}/os/running-rancheros/cloud/aws)
[Google Compute Engine]({{site.baseurl}}/os/running-rancheros/cloud/gce)
[DigitalOcean]({{site.baseurl}}/os/running-rancheros/cloud/do)
[Azure]({{site.baseurl}}/os/running-rancheros/cloud/azure)
#### Bare Metal & Virtual Servers
[iPXE]({{site.baseurl}}/os/running-rancheros/server/ipxe)
[PXE]({{site.baseurl}}/os/running-rancheros/server/pxe)
[Install to Hard Disk]({{site.baseurl}}/os/running-rancheros/server/install-to-disk)
<br>

100
docs/os/running-rancheros/server/install-to-disk/index.md Normal file
View File

@@ -0,0 +1,100 @@
---
title: Installing RancherOS to Disk
layout: os-default
---
## Installing RancherOS to Disk
---
RancherOS comes with a simple installer that will install RancherOS on a given target disk. To install RancherOS on a new disk, you can use the `ros install` command. Before installing, you'll need to have already [booted RancherOS from ISO]({{site.baseurl}}/os/running-rancheros/workstation/boot-from-iso). Please be sure to pick the `rancheros.iso` from our release [page](https://github.com/rancher/os/releases).
### Using `ros install` to Install RancherOS
The `ros install` command orchestrates the installation from the `rancher/os` container. You will need to have already created a cloud-config file and found the target disk.
#### Cloud-Config
The easiest way to log in is to pass a `cloud-config.yml` file containing your public SSH keys. To learn more about what's supported in our cloud-config, please read our [documentation]({{site.baseurl}}/os/configuration/#cloud-config).
The `ros install` command will process your `cloud-config.yml` file specified with the `-c` flag. This file will also be placed onto the disk and installed to `/var/lib/rancher/conf/`. It will be evaluated on every boot.
Create a cloud-config file with a SSH key, this allows you to SSH into the box as the rancher user. The yml file would look like this:
```yaml
#cloud-config
ssh_authorized_keys:
- ssh-rsa AAA...
```
<br>
You can generate a new SSH key for `cloud-config.yml` file by following this [article](https://help.github.com/articles/generating-ssh-keys/).
Copy the public SSH key into RancherOS before installing to disk.
Now that our `cloud-config.yml` contains our public SSH key, we can move on to installing RancherOS to disk!
```
$ sudo ros install -c cloud-config.yml -d /dev/sda
INFO[0000] No install type specified...defaulting to generic
Installing from rancher/os:v0.5.0
Continue [y/N]:
```
You will be prompted to see if you want to continue. Type **y**.
```
Unable to find image 'rancher/os:v0.5.0' locally
v0.5.0: Pulling from rancher/os
...
...
...
Status: Downloaded newer image for rancher/os:v0.5.0
+ DEVICE=/dev/sda
...
...
...
+ umount /mnt/new_img
Continue with reboot [y/N]:
```
After installing RancherOS to disk, you will no longer be automatically logged in as the `rancher` user. You'll need to have added in SSH keys within your [cloud-config file]({{site.baseurl}}/os/configuration/#cloud-config).
#### Installing a Different Version
By default, `ros install` uses the same installer image version as the ISO it is run from. The `-i` option specifies the particular image to install from. To keep the ISO as small as possible, the installer image is downloaded from DockerHub and used in System Docker. For example for RancherOS v0.5.0 the default installer image would be `rancher/os:v0.5.0`.
You can use `ros os list` command to find the list of available RancherOS images/versions.
```
$ sudo ros os list
rancher/os:v0.4.0 remote
rancher/os:v0.4.1 remote
rancher/os:v0.4.2 remote
rancher/os:v0.4.3 remote
rancher/os:v0.4.4 remote
rancher/os:v0.4.5 remote
rancher/os:v0.5.0 remote
```
Alternatively, you can set the installer image to any image in System Docker to install RancherOS. This is particularily useful for machines that will not have direct access to the internet.
### SSH into RancherOS
After installing RancherOS, you can ssh into RancherOS using your private key and the **rancher** user.
```
$ ssh -i /path/to/private/key rancher@<ip-address>
```
### Installing with no Internet Access
If you'd like to install RancherOS onto a machine that has no internet access, it is assumed you either have your own private registry or other means of distributing docker images to System Docker of the machine. If you need help with creating a private registry, please refer to the [Docker documentation for private registries](https://docs.docker.com/registry/).
In the installation command (i.e. `sudo ros install`), there is an option to pass in a specific image to install. As long as this image is available in System Docker, then RancherOS will use that image to install RancherOS.
```
$ sudo ros install -c cloud-config.yml -d /dev/sda -i <Image_Name_in_System_Docker>
INFO[0000] No install type specified...defaulting to generic
Installing from <Image_Name_in_System_Docker>
Continue [y/N]:
```

37
docs/os/running-rancheros/server/pxe/index.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Booting RancherOS with iPXE
layout: os-default
---
## Booting RancherOS via iPXE
----
```
#!ipxe
# Boot a persistent RancherOS to RAM
# Location of Kernel/Initrd images
set base-url http://releases.rancher.com/os/latest
kernel ${base-url}/vmlinuz rancher.state.dev=LABEL=RANCHER_STATE rancher.state.autoformat=[/dev/sda] rancher.cloud_init.datasources=[url:http://example.com/cloud-config]
initrd ${base-url}/initrd
boot
```
### Datasources
Valid [datasources](https://github.com/rancher/os/blob/3338c4ac63597940bcde7e6005f1cc09287062a2/cmd/cloudinit/cloudinit.go#L378) for RancherOS.
| type | default |
|---|---|
| ec2 | DefaultAddress |
| file | path |
| url | url |
| cmdline | |
| configdrive | |
| digitalocean | DefaultAddress |
| gce | |
### Cloud-Config
When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{site.baseurl}}/os/configuration/#cloud-config).

34
docs/os/running-rancheros/server/raspberry-pi/index.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: Running RancherOS on Raspberry Pi
layout: os-default
---
## Raspberry Pi
---
As of v0.5.0, RancherOS releases include a Raspberry Pi image that can be found on our [releases page](https://github.com/rancher/os/releases). The official Raspberry Pi documentation contains instructions on how to [install operating system images](https://www.raspberrypi.org/documentation/installation/installing-images/).
When installing, there is no ability to pass in a [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes.
Currently, only Raspberry Pi 2 and 3 are tested and known to work.
### Using the entire SD Card
RancherOS does not currently expand the root partition to fill the remainder of the SD card automatically. Instead, the following workaround can be used to store Docker containers on a larger partition that fills the remainder.
1. `sudo fdisk /dev/mmcblk0`
2. Create a `n`ew partition
3. Press `[Enter]` four (4x) times to accept the defaults
4. Then `w`rite the table and exit
5. `sudo reboot` to reboot and reload the new partition table
6. `sudo mkdir /mnt/docker` to create the directory to be used as the new Docker root
7. `sudo ros config set rancher.docker.extra_args [-g,/mnt/docker]` to configure Docker to use the new root
8. `sudo mkfs.ext4 /dev/mmcblk0p3` to format the disk
9. `sudo ros config set mounts "[['/dev/mmcblk0p3','/mnt/docker','ext4','']]"` to preserve this mount after reboots
10. `sudo mount /dev/mmcblk0p3 /mnt/docker` to mount the Docker root
11. `sudo system-docker restart docker` to restart Docker using the new root
If this is not a new installation, you'll have to copy over your existing Docker root (`/var/lib/docker`) to the new root (`/mnt/docker`).
1. `sudo cp -R /var/lib/docker/* /mnt/docker` to recursively copy all files
2. `sudo system-docker restart docker` to restart Docker using the new root

86
docs/os/running-rancheros/workstation/boot-from-iso/index.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: Booting from ISO
layout: os-default
---
## Boot from ISO
---
The RancherOS ISO file can be used to create a fresh RancherOS install on KVM, VMware, VirtualBox, or bare metal servers. You can download the `rancheros.iso` file from our [releases page](https://github.com/rancher/os/releases/).
You must boot with at least **512MB** of memory. If you boot with the ISO, you will automatically be logged in as the `rancher` user. Only the ISO is set to use autologin by default. If you run from a cloud or install to disk, SSH keys or a password of your choice is expected to be used.
> **Note:** If you are planning on [installing to disk]({{site.baseurl}}/os/running-rancheros/server/install-to-disk/), you will need at least 1.5GB of RAM.
### Install to Disk
---
After you boot RancherOS from ISO, you can follow the instructions [here]({{site.baseurl}}/os/running-rancheros/server/install-to-disk/) to install RancherOS to a hard disk.
### Persisting State
---
If you are running from the ISO, RancherOS will be running from memory. All downloaded Docker images, for example, will be stored in a ramdisk and will be lost after the server is rebooted. You can
create a file system with the label `RANCHER_STATE` to instruct RancherOS to use that partition to store state. Suppose you have a disk partition on the server called `/dev/sda`, the following command formats that partition and labels it `RANCHER_STATE`
```
$ sudo mkfs.ext4 -L RANCHER_STATE /dev/sda
# Reboot afterwards in order for the changes to start being saved.
$ sudo reboot
```
After you reboot, the server RancherOS will use `/dev/sda` as the state partition.
> **Note:** If you are installing RancherOS to disk, you do not need to run this command.
<!----
### Example using VirtualBox
1. Download the RancherOS ISO.
2. Start up a VM from VirtualBox.
a. Open up VirtualBox. If you don't have VirtualBox, download it [here](https://www.virtualbox.org/wiki/Downloads).
![RancherOS on ISO 1]({{site.baseurl}}/img/os/Rancher_iso1.png)
b. Provide a **name**, select the **type** to be _Linux_, and select the **version** to be _Other Linux (64-bit)_. Click **Continue**.
![RancherOS on ISO 2]({{site.baseurl}}/img/os/Rancher_iso2.png)
c. Select at least **1GB** of RAM.
![RancherOS on ISO 3]({{site.baseurl}}/img/os/Rancher_iso3.png)
d. Select **Create a virtual hard drive now** and click **Create**.
![RancherOS on ISO 4]({{site.baseurl}}/img/os/Rancher_iso4.png)
e. Select the **VDI (VirtualBox Disk Image)** setting and click **Continue**.
![RancherOS on ISO 5]({{site.baseurl}}/img/os/Rancher_iso5.png)
f. Select **Dynamically allocated** and click **Continue**.
![RancherOS on ISO 6]({{site.baseurl}}/img/os/Rancher_iso6.png)
g. Click **Create**.
![RancherOS on ISO 7]({{site.baseurl}}/img/os/Rancher_iso7.png)
Your new VM should be created, but in a _Powered Off_ state.
3. Start the VM from VirtualBox by clicking on the VM and clicking **Start** or right-click on the box and select **Start**. You will be immediately prompted to select an ISO. Find the RancherOS ISO that you have downloaded. Click **Start**.
![RancherOS on ISO 7]({{site.baseurl}}/img/os/Rancher_iso7.png)
4. When RancherOS launches, you will be prompted for a rancher login and password. The login and password is 'rancher' (all lowercase).
```
RancherOS rancher /dev/ttyl
rancher login: rancher
Password:
```
Next, read about how to [install to disk]({{site.baseurl}}/os/running-rancheros/server/install-to-disk/) in order to have any changes to RancherOS to be saved.
---->

84
docs/os/running-rancheros/workstation/docker-machine/index.md Normal file
View File

@@ -0,0 +1,84 @@
---
title: Using Docker Machine to run RancherOS
layout: os-default
---
## Docker Machine
---
Before we get started, you'll need to make sure that you have docker machine installed. Download it directly from the docker machine [releases](https://github.com/docker/machine/releases).
> **Note:** If you create a RancherOS instance using Docker Machine, you will not be able to upgrade your version of RancherOS.
### Downloading RancherOS
Get the latest `rancheros.iso` artifact from the RancherOS [releases](https://github.com/rancher/os/releases).
### Using Docker Machine
You can use Docker Machine to launch VMs for various providers. Currently only VirtualBox and AWS are supported.
#### Using Docker Machine with VirtualBox
Before moving forward, you'll need to have VirtualBox installed. Download it directly from [VirtualBox](https://www.virtualbox.org/wiki/Downloads). Once you have VirtualBox and Docker Machine installed, it's just one command to get RancherOS running.
```
$ docker-machine create -d virtualbox --virtualbox-boot2docker-url <LOCATION-OF-RANCHEROS-ISO> <MACHINE-NAME>
```
<br>
> **Note:** Instead of downloading the ISO, you can directly use the URL for the `rancheros.iso`.
Example using the RancherOS latest link:
```
$ docker-machine create -d virtualbox --virtualbox-boot2docker-url https://releases.rancher.com/os/latest/rancheros.iso <MACHINE-NAME>
```
That's it! You should now have a RancherOS host running on VirtualBox. You can verify that you have a VirtualBox VM running on your host.
> **Note:** After the machine is created, Docker Machine may display some errors regarding creation, but if the VirtualBox VM is running, you should be able to [log in](#logging-into-rancheros).
```
$ VBoxManage list runningvms | grep <MACHINE-NAME>
```
This command will print out the newly created machine. If not, something went wrong with the provisioning step.
### Logging into RancherOS
Logging into RancherOS follows the standard Docker Machine commands. To login into your newly provisioned RancherOS VM.
```
$ docker-machine ssh <MACHINE-NAME>
```
You'll be logged into RancherOS and can start exploring the OS, This will log you into the RancherOS VM. You'll then be able to explore the OS by [adding system services]({{site.baseurl}}/os/system-services/adding-system-services/), [customizing the configuration]({{site.baseurl}}/os/configuration/), and launching containers.
If you want to exit out of RancherOS, you can exit by pressing `Ctrl+D`.
### Docker Machine Benefits
With Docker Machine, you can point the docker client on your host to the docker daemon running inside of the VM. This allows you to run your docker commands as if you had installed docker on your host.
To point your docker client to the docker daemon inside the VM, use the following command:
```
$ eval $(docker-machine env <MACHINE-NAME>)
```
After setting this up, you can run any docker command in your host, and it will execute the command in your RancherOS VM.
```
$ docker run -p 80:80 -p 443:443 -d nginx
```
In your VM, a nginx container will start on your VM. To access the container, you will need the IP address of the VM.
```
$ docker-machine ip <MACHINE-NAME>
```
Once you obtain the IP address, paste it in a browser and a _Welcome Page_ for nginx will be displayed.

28
docs/os/storage/additional-mounts/index.md Normal file
View File

@@ -0,0 +1,28 @@
---
title: Additional Mounts in RancherOS
layout: os-default
redirect_from:
- os/configuration/additional-mounts/
---
## Additional Mounts
Additional mounts can be specified as part of your [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config). These mounts are applied within the console container. Here's a simple example that mounts `/dev/vdb` to `/mnt/s`.
```yaml
#cloud-config
mounts:
- ["/dev/vdb", "/mnt/s", "ext4", ""]
```
<br>
The four arguments for each mount are the same as those given for [cloud-init](https://cloudinit.readthedocs.io/en/latest/topics/examples.html#adjust-mount-points-mounted). Only the first four arguments are currently supported. The `mount_default_fields` key is not yet implemented.
RancherOS uses the mount syscall rather than the `mount` command behind the scenes. This means that `auto` cannot be used as the filesystem type (third argument) and `defaults` cannot be used for the options (forth argument).
### Shared Mounts
By default, `/media` and `/mnt` are mounted as shared in the console container. This means that mounts within these directories will propogate to the host as well as other system services that mount these folders as shared.
See [here](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) for a more detailed overview of shared mounts and their properties.

28
docs/os/storage/state-partition/index.md Normal file
View File

@@ -0,0 +1,28 @@
---
title: Persistent State Partition in RancherOS
layout: os-default
---
## Persistent State Partition
RancherOS will store its state in a single partition specified by the `dev` field. The field can be a device such as `/dev/sda1` or a logical name such `LABEL=state` or `UUID=123124`. The default value is `LABEL=RANCHER_STATE`. The file system type of that partition can be set to `auto` or a specific file system type such as `ext4`.
```yaml
#cloud-config
rancher:
state:
fstype: auto
dev: LABEL=RANCHER_STATE
autoformat:
- /dev/sda
- /dev/vda
```
### Autoformat
You can specify a list of devices to check to format on boot. If the state partition is already found, RancherOS will not try to auto format a partition. By default, auto-formatting is off.
RancherOS will autoformat the partition to ext4 if the device specified in `autoformat`:
* Contains a boot2docker magic string
* Starts with 1 megabyte of zeros and `rancher.state.formatzero` is true

142
docs/os/storage/using-zfs/index.md Normal file
View File

@@ -0,0 +1,142 @@
---
title: Using ZFS in RancherOS
layout: os-default
redirect_from:
- os/configuration/storage/
---
## Using ZFS
In order to start using ZFS, you'll need to first enable one of the [persistent consoles]({{site.baseurl}}/os/configuration/custom-console/#console-persistence) and enable [kernel headers]({{site.baseurl}}/os/configuration/kernel-modules-kernel-headers/).
```
$ sudo ros console switch ubuntu
$ sudo ros service enable kernel-headers
$ sudo ros service up -d kernel-headers
```
When RancherOS console has reloaded, you will have logged into the persistent console. The current kernel headers will need to be downloaded using the `ros service enable` and the service will be started with `ros service up -d kernel-headers`.
#### Installing ZFS on Ubuntu Console
Based on the [Ubuntu ZFS docs](https://wiki.ubuntu.com/Kernel/Reference/ZFS), you only need to install `zfs` package into the Ubuntu console to enable ZFS. All the other necessary packages will be installed as its dependencies.
```
$ sudo apt update
$ sudo apt install zfs
```
#### Mounting ZFS filesystems on boot
In order for ZFS to load on boot, it needs to be added to `modules` list in the config. Prior to adding it to the list of modules, you'll need to check to see if there are other modules that are currently enabled.
```
# Check to see what modules currently exist
$ sudo ros config get rancher.modules
# Make sure to include any modules that were already enabled
$ sudo ros config set rancher.modules [zfs]
```
<br>
You will also need to have the zpool cache imported on boot:
```
[ -f /etc/zfs/zpool.cache ] && zpool import -c /etc/zfs/zpool.cache -a
```
<br>
A cloud-config `runcmd` instruction will do it for you:
```
# check current 'runcmd' list
$ sudo ros config get runcmd
[]
# add the command we need to run on boot
$ sudo ros config set runcmd "[[sh, -c, '[ -f /etc/zfs/zpool.cache ] && zpool import -c /etc/zfs/zpool.cache -a']]"
```
#### Using ZFS
After it's installed, it should be ready to use!
```
$ sudo modprobe zfs
$ sudo zpool list
$ sudo zpool create zpool1 /dev/<some-disk-dev>
```
<br>
To experiment with ZFS, you can create zpool backed by just ordinary files, not necessarily real block devices. In fact, you can mix storage devices in your ZFS pools; it's perfectly fine to create a zpool backed by real devices **and** ordinary files.
## ZFS storage for Docker on RancherOS
First, you need to stop the`docker` system service and wipe out `/var/lib/docker` folder:
```
$ sudo system-docker stop docker
$ sudo rm -rf /var/lib/docker/*
```
To enable ZFS as the storage driver for Docker, you'll need to create a ZFS filesystem for Docker and make sure it's mounted.
```
$ sudo zfs create zpool1/docker
$ sudo zfs list -o name,mountpoint,mounted
```
At this point you'll have a ZFS filesystem created and mounted at `/zpool1/docker`. According to [Docker ZFS storage docs](https://docs.docker.com/engine/userguide/storagedriver/zfs-driver/), if the Docker root dir is a ZFS filesystem, the Docker daemon will automatically use `zfs` as its storage driver.
Now you'll need to remove `-s overlay` (or any other storage driver) from the Docker daemon args to allow docker to automatically detect `zfs`.
```
$ sudo ros config set rancher.docker.storage_driver ''
$ sudo ros config set rancher.docker.graph /zpool1/docker
# After editing Docker daemon args, you'll need to start Docker
$ sudo system-docker start docker
```
After customizing the Docker daemon arguments and restarting `docker` system service, ZFS will be used as Docker storage driver:
```
$ docker info
Containers: 1
Running: 0
Paused: 0
Stopped: 1
Images: 1
Server Version: 1.12.1
Storage Driver: zfs
Zpool: zpool1
Zpool Health: ONLINE
Parent Dataset: zpool1/docker
Space Used By Parent: 27761152
Space Available: 4100088320
Parent Quota: no
Compression: off
Logging Driver: json-file
Cgroup Driver: cgroupfs
Plugins:
Volume: local
Network: host null bridge overlay
Swarm: inactive
Runtimes: runc
Default Runtime: runc
Security Options: seccomp
Kernel Version: 4.4.16-rancher
Operating System: RancherOS v0.6.0-rc8
OSType: linux
Architecture: x86_64
CPUs: 2
Total Memory: 1.938 GiB
Name: rancher
ID: EK7Q:WTBH:33KR:UCRY:YAPI:N7RX:D25K:S7ZH:DRNY:ZJ3J:25XE:P3RF
Docker Root Dir: /zpool1/docker
Debug Mode (client): false
Debug Mode (server): false
Registry: https://index.docker.io/v1/
Insecure Registries:
127.0.0.0/8
```

133
docs/os/system-services/adding-system-services/index.md Normal file
View File

@@ -0,0 +1,133 @@
---
title: Adding System Services in RancherOS
layout: os-default
redirect_from:
- os/system-services/
- os/configuration/system-services/
---
## System Services
A system service is a container that can be run in either System Docker or Docker. Rancher provides services that are already available in RancherOS by adding them to the [os-services repo](https://github.com/rancher/os-services). Anything in the `index.yml` file from the repository for the tagged release will be an available system service when using the `ros service list` command.
### Enabling and Starting System Services
For any services that are listed from the `ros service list`, they can be enabled by running a single command. After enabling a service, you will need to run start the service.
```
# List out available system services
$ sudo ros service list
disabled amazon-ecs-agent
disabled kernel-headers
disabled kernel-headers-system-docker
disabled open-vm-tools
# Enable a system service
$ sudo ros service enable kernel-headers
# Start a system service
$ sudo ros service up -d kernel-headers
```
### Disabling and Removing System Services
In order to stop a system service from running, you will need to stop and disable the system service.
```
# List out available system services
$ sudo ros service list
disabled amazon-ecs-agent
enabled kernel-headers
disabled kernel-headers-system-docker
disabled open-vm-tools
# Disable a system service
$ sudo ros service disable kernel-headers
# Stop a system service
$ sudo ros service stop kernel-headers
# Remove the containers associated with the system service
$ sudo ros service down kernel-headers
```
<br>
If you want to remove a system service from the list of service, just delete the service.
```
$ sudo ros service delete <serviceName>
```
### Custom System Services
You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS.
#### Launching Services through Cloud-Config
If you want to boot RancherOS with a system service running, you can add the service to the cloud-config that is passed to RancherOS. When RancherOS starts, this service will automatically be started.
```yaml
#cloud-config
rancher:
services:
nginxapp:
image: nginx
restart: always
```
#### Launching Custom System Services inside RancherOS
If you already have RancherOS running, you can start a system service by saving a `docker-compose.yml` file at `/var/lib/rancher/conf/`.
```yaml
nginxapp:
image: nginx
restart: always
```
To enable a custom system service from the file location, the command must indicate the file location if saved in RancherOS. If the file is saved at a http(s) url, just use the http(s) url when enabling/disabling.
```
# Enable the system service saved in /var/lib/rancher/conf
$ sudo ros service enable /var/lib/rancher/conf/example.yml
# Enable a system service saved at a http(s) url
$ sudo ros service enable https://mydomain.com/example.yml
```
<br>
After the custom system service is enabled, you can start the service using `sudo ros service up -d <serviceName>`. The `<serviceName>` will be the names of the services inside the `docker-compose.yml`.
```
$ sudo ros service up -d nginxapp
# If you have more than 1 service in your docker-compose.yml, add all service names to the command
$ sudo ros service up -d service1 service2 service3
```
### System Docker vs. Docker
RancherOS uses labels to determine if the container should be deployed in System Docker. By default without the label, the container will be deployed in Docker.
```yaml
labels:
- io.rancher.os.scope=system
```
### Labels
We use labels to determine how to handle the service containers.
Key | Value |Description
----|-----|---
`io.rancher.os.detach` | Default: `true` | Equivalent of `docker run -d`. If set to `false`, equivalent of `docker run --detach=false`
`io.rancher.os.scope` | `system` | Use this label to have the container deployed in System Docker instead of Docker.
`io.rancher.os.before`/`io.rancher.os.after` | Service Names (Comma separated list is accepted) | Used to determine order of when containers should be started.
`io.rancher.os.createonly` | Default: `false` | When set to `true`, only a `docker create` will be performed and not a `docker start`.
`io.rancher.os.reloadconfig` | Default: `false`| When set to `true`, it reloads the configuration.
#### Example of how to order container deployment
```yaml
foo:
labels:
# Start foo before bar is launched
io.rancher.os.before: bar
# Start foo after baz has been launched
io.rancher.os.after: baz
```

109
docs/os/system-services/built-in-system-services/index.md Normal file
View File

@@ -0,0 +1,109 @@
---
title: Built-in System Services in RancherOS
layout: os-default
---
## Built-in System Services
To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{site.baseurl}}/os/system-services/) or override services in the cloud-config.
In start up order, here are the groups of services:
1. Device and power management:
- udev-cold
- udev
- acpid
2. syslog
3. System configuration and networking:
- preload-system-images
- cloud-init-pre
- network-pre
- ntp
- cloud-init
- network
4. User interaction:
- console
- docker
5. Post configuration:
- preload-user-images
### preload-system-images & preload-user-images
Read more about [pre-packing Docker images]({{site.baseurl}}/os/configuration/prepacking-docker-images/).
### cloud-init-pre
User-data (i.e. [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config)) and metadata from cloud provider, VM runtime, or a management service, is loaded in this service.
The user-data is written to:
* `/var/lib/rancher/conf/cloud-config.d/boot.yml` - If the user-data is a cloud-config, i.e. begins with `#cloud-config` and is YAML format.
* `/var/lib/rancher/conf/cloud-config-script` - If the user-data is a script, i.e begins with `#!`.
* `/var/lib/rancher/conf/metadata` - If it is serialized cloud provider metadata.
It is configured by the `rancher.cloud_init.datasources` list in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config). It is pre-configured in cloud-provider specific images (e.g. AWS, GCE).
### network-pre
During this service, networking is set up, e.g. hostname, interfaces, and DNS.
It is configured by `hostname` and `rancher.network`[settings]({{site.baseurl}}/os/networking/) in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
### ntp
Runs `ntpd` in a System Docker container.
### cloud-init
It does the same thing as cloud-init-pre, but in this step, it can also use the network to fetch user-data and metadata (e.g. in cloud providers).
### network
Completes setting up networking with configuration obtained by cloud-init.
### console
This service provides the RancherOS user interface by running `sshd` and `getty`. It completes the RancherOS configuration on start up:
1. If the `rancher.password=<password>` kernel parameter exists, it sets `<password>` as the password for the `rancher` user.
2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
3. Runs `cloud-init -execute`, which does the following:
* Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{site.baseurl}}/os/configuration/ssh-keys/) and metadata.
* Writes files specified by the `write_files` [cloud-config]({{site.baseurl}}/os/configuration/write-files/) setting.
* Resizes the device specified by the `rancher.resize_device` [cloud-config]({{site.baseurl}}/os/configuration/resizing-device-partition/) setting.
* Mount devices specified in the `mounts` [cloud-config]({{site.baseurl}}/os/configuration/additional-mounts/) setting.
* Set sysctl parameters specified in the`rancher.sysctl` [cloud-config]({{site.baseurl}}/os/configuration/sysctl/) setting.
4. If user-data contained a file that started with `#!`, then a file would be saved at `/var/lib/rancher/conf/cloud-config-script` during cloud-init and then executed. Any errors are ignored.
5. Runs `/opt/rancher/bin/start.sh` if it exists and is executable. Any errors are ignored.
6. Runs `/etc/rc.local` if it exists and is executable. Any errors are ignored.
### docker
This system service runs the user docker daemon. Normally it runs inside the console system container by running `docker-init` script which, in turn, looks for docker binaries in `/opt/bin`, `/usr/local/bin` and `/usr/bin`, adds the first found directory with docker binaries to PATH and runs `dockerlaunch docker daemon` appending the passed arguments.
Docker daemon args are read from `rancher.docker.args` cloud-config property (followed by `rancher.docker.extra_args`).
### RancherOS Configuration Load Order
[Cloud-config]({{site.baseurl}}/os/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file.
1. `/usr/share/ros/os-config.yml` - This is the system default configuration, which should **not** be modified by users.
2. `/usr/share/ros/oem/oem-config.yml` - This will typically exist by OEM, which should **not** be modified by users.
3. Files in `/var/lib/rancher/conf/cloud-config.d/` ordered by filename. If a file is passed in through user-data, it is written by cloud-init and saved as `/var/lib/rancher/conf/cloud-config.d/boot.yml`.
4. `/var/lib/rancher/conf/cloud-config.yml` - If you set anything with `ros config set`, the changes are saved in this file.
5. Kernel parameters with names starting with `rancher`.
6. `/var/lib/rancher/conf/metadata` - Metadata added by cloud-init.

36
docs/os/system-services/environment/index.md Normal file
View File

@@ -0,0 +1,36 @@
---
title: Environment
layout: os-default
---
## Environment
---
The [environment key](https://docs.docker.com/compose/yml/#environment) can be used to customize system services. When a value is not assigned, RancherOS looks up the value from the `rancher.environment` key.
In the example below, `ETCD_DISCOVERY` will be set to `https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7` for the `etcd` service.
```yaml
rancher:
environment:
ETCD_DISCOVERY: https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7
services:
etcd:
...
environment:
- ETCD_DISCOVERY
```
Wildcard globbing is also supported. In the example below, `ETCD_DISCOVERY` will be set as in the previous example, along with any other environment variables beginning with `ETCD_`.
```yaml
rancher:
environment:
ETCD_DISCOVERY: https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7
services:
etcd:
...
environment:
- ETCD_*
```

79
docs/os/system-services/system-docker-volumes/index.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: System Docker Volumes
layout: os-default
---
## System Docker Volumes
---
A few services are containers in `created` state. Their purpose is to provide volumes for other services.
### user-volumes
Provides user accessible persistent storage directories, used by console service:
```
/home
/opt
```
### container-data-volumes
Provides docker storage directory, used by console service (and, indirectly, by docker)
```
/var/lib/docker
```
### command-volumes
Provides necessary command binaries (read-only), used by system services:
```
/usr/bin/docker-containerd.dist
/usr/bin/docker-containerd-shim.dist
/usr/bin/docker-runc.dist
/usr/bin/docker.dist
/usr/bin/dockerlaunch
/usr/bin/user-docker
/usr/bin/system-docker
/sbin/poweroff
/sbin/reboot
/sbin/halt
/sbin/shutdown
/usr/bin/respawn
/usr/bin/ros
/usr/bin/cloud-init
/usr/sbin/netconf
/usr/sbin/wait-for-docker
/usr/bin/switch-console
```
### system-volumes
Provides necessary persistent directories, used by system services:
```
/host/dev
/etc/docker
/etc/hosts
/etc/resolv.conf
/etc/ssl/certs/ca-certificates.crt.rancher
/etc/selinux
/lib/firmware
/lib/modules
/run
/usr/share/ros
/var/lib/rancher/cache
/var/lib/rancher/conf
/var/lib/rancher
/var/log
/var/run
```
### all-volumes
Combines all of the above, used by the console service.

10
docs/os/under-the-hood/device-plug-and-unplug/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Device Plug and Unplug
layout: os-default
---
## Device Plug and Unplug
---
More information coming soon!

19
docs/os/under-the-hood/directories/index.md Normal file
View File

@@ -0,0 +1,19 @@
---
title: Directories
layout: os-default
---
## How directories are mounted, Ram disk, etc.
---
### Persistent Directories Across Reboot
With v0.4.0, ubuntu and debian consoles are [persistent consoles]({{site.baseurl}}/os/configuration/custom-console/#console-persistence). Therefore, the only difference is what is persisted inside a containers as opposed to on the host. If a container is deleted/rebuilt, state in the console will be lost except what is in the persisted directories.
```
/home
/opt
/var/lib/docker
/var/lib/rancher
```

8
docs/os/under-the-hood/porting/index.md Normal file
View File

@@ -0,0 +1,8 @@
---
title: Porting
layout: os-default
---
## Porting

10
docs/os/under-the-hood/startup-sequence/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Startup Sequence
layout: os-default
---
## RancherOS Startup Sequence
---
More information coming soon!

10
docs/os/under-the-hood/zombie-process-management/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Zombie process management
layout: os-default
---
## Zombie Process Management (Our hack on Docker Daemon)
---
More information coming soon!

138
docs/os/upgrading/index.md Normal file
View File

@@ -0,0 +1,138 @@
---
title: Upgrading RancherOS
layout: os-default
---
## Upgrading
---
If RancherOS has released a new version and you want to learn how to upgrade your OS, we make it easy using the `ros os` command.
Since RancherOS is a kernel and initrd, the upgrade process is downloading a new kernel and initrd, and updating the boot loader to point to it. The old kernel and initrd are not removed. If there is a problem with your upgrade, you can select the old kernel from the bootloader, which is grub2 by default.
To see all of our releases, please visit our [releases page](https://github.com/rancher/os/releases) in GitHub.
### Version Control
First, let's check what version you have running on your system.
```
$ sudo ros os version
v0.4.5
```
If you just want to find out the available releases from the command line, it's a simple command.
```
# List all available releases
$ sudo ros os list
rancher/os:v0.4.0 remote
rancher/os:v0.4.1 remote
rancher/os:v0.4.2 remote
rancher/os:v0.4.3 remote
rancher/os:v0.4.4 remote
rancher/os:v0.4.5 remote
rancher/os:v0.5.0 local
```
The `local`/`remote` label shows which images are available to System Docker locally versus which need to be pulled from Docker Hub. If you choose to upgrade to a version that is remote, we will automatically pull that image during the upgrade.
### Upgrading
Let's walk through upgrading! The `ros os upgrade` command will automatically upgrade to the current release of RancherOS. The current release is designated as the most recent release of RancherOS.
```
$ sudo ros os upgrade
Upgrading to rancher/os:v0.5.0
```
Confirm that you want to continue and the final step will be to confirm that you want to reboot.
```
Continue [y/N]: y
...
...
...
Continue with reboot [y/N]: y
INFO[0037] Rebooting
```
After rebooting, you can check that your version has been updated.
```
$ sudo ros -v
ros version v0.5.0
```
> **Note:** If you are booting from ISO and have not installed to disk, your upgrade will not be saved. You can view our guide to [installing to disk]({{site.baseurl}}/os/running-rancheros/server/install-to-disk/).
#### Upgrading to a Specific Version
If you are a couple of versions behind the current version, use the `-i` option to pick the version that you want to upgrade to.
```
$ sudo ros os upgrade -i rancher/os:v0.5.0
Upgrading to rancher/os:v0.5.0
Continue [y/N]: y
...
...
...
Continue with reboot [y/N]: y
INFO[0082] Rebooting
```
#### Bypassing The Prompts
We have added the ability to bypass the prompts. Use the `-f` or `--force` option when upgrading. Your machine will automatically be rebooted and you'll just need to log back in when it's done.
If you want to bypass the prompts, but you don't want to immediately reboot, you can add `--no-reboot` to avoid rebooting immediately.
### Rolling back an Upgrade
If you've upgraded your RancherOS and something's not working anymore, you can easily rollback your upgrade.
The `ros os upgrade` command works for rolling back. We'll use the `-i` option to "upgrade" to a specific version. All you need to do is pick the previous version! Same as before, you will be prompted to confirm your upgrade version as well as confirm your reboot.
```
$ sudo ros -v
ros version v0.4.5
$ sudo ros os upgrade -i rancher/os:v0.4.4
Upgrading to rancher/os:v0.4.4
Continue [y/N]: y
...
...
...
Continue with reboot [y/N]: y
INFO[0082] Rebooting
```
After rebooting, the rollback will be complete.
```
$ sudo ros -v
ros version 0.4.4
```
<br>
> **Note:** If you are using a [persistent console]({{site.baseurl}}/os/configuration/custom-console/#console-persistence) and in the current version's console, rolling back is not supported. For example, rolling back to v0.4.5 when using a v0.5.0 persistent console is not supported.
### Staging an Upgrade
During an upgrade, the template of the upgrade is downloaded from the rancher/os repository. You can download this template ahead of time so that it's saved locally. This will decrease the time it takes to upgrade. We'll use the `-s` option to stage the specific template. You will need to specify the image name with the `-i` option, otherwise it will automatically stage the current version.
```
$ sudo ros os upgrade -s -i rancher/os:v0.5.0
```
### Custom Upgrade Sources
In the `upgrade` key, the `url` is used to find the list of available and current versions of RancherOS. This can be modified to track custom builds and releases.
```yaml
#cloud-config
rancher:
upgrade:
url: https://releases.rancher.com/os/releases.yml
image: rancher/os
```