diff --git a/content/os/_index.md b/content/os/_index.md new file mode 100644 index 00000000000..9998f393af1 --- /dev/null +++ b/content/os/_index.md @@ -0,0 +1,47 @@ +--- +tag: ["rancheros", "os", "overview"] +category: ["os"] +layout: list-docs +title: RancherOS Documentation +description: RancherOS is a simplified Linux distribution built from containers, for containers. These documents describe how to install and use RancherOS. +weight: 1 +--- + +## 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`. Because it only includes the services necessary to run Docker, RancherOS is dramatically smaller than most traditional operating systems. 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/engine/userguide/). + +### Hardware Requirements + +* x86_64 server with at least 512MB of RAM. + +> **Note:** If you are planning on [installing to disk]({{page.osbaseurl}}/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]({{page.osbaseurl}}/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]({{page.osbaseurl}}/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). + +
+
diff --git a/content/os/about/_index.md b/content/os/about/_index.md new file mode 100644 index 00000000000..abc83e2a9b2 --- /dev/null +++ b/content/os/about/_index.md @@ -0,0 +1,80 @@ +--- +tag: ["rancheros", "os", "faqs"] +category: "os" +layout: list-docs +title: About +weight: 300 +--- + +## 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.) + +To run just one integration test, or a group of them (using regex's like `.*Console.*`, you can set the `RUNTEST` environment variable: + +``` +$ RUNTEST=TestPreload make integration-test +``` + +### 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 in the console 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`, `rancher.system_docker.debug`, `rancher.bootstrap_docker.debug`, or `rancher.log` individually. + +You will also be able to view the debug logging information by running `dmesg` as root. + +## 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]({{page.osbaseurl}}/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). + +
+
diff --git a/content/os/about/faqs/_index.md b/content/os/about/faqs/_index.md new file mode 100644 index 00000000000..c980f664add --- /dev/null +++ b/content/os/about/faqs/_index.md @@ -0,0 +1,33 @@ +--- +tag: ["rancheros", "os", "faqs"] +category: "os" +layout: list-docs +title: FAQs +weight: 301 +--- + +## 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 + + +### How can I extend my disk size in Amazon? + +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. diff --git a/content/os/about/running-rancher-on-rancherOS/_index.md b/content/os/about/running-rancher-on-rancherOS/_index.md new file mode 100644 index 00000000000..efdb455eeb0 --- /dev/null +++ b/content/os/about/running-rancher-on-rancherOS/_index.md @@ -0,0 +1,104 @@ +--- +tag: ["rancheros", "os", "rancher"] +category: "os" +layout: list-docs +title: Running Rancher on RancherOS +weight: 302 +--- + + +## Tips on using Rancher with RancherOS +--- + +RancherOS can be used to launch [Rancher]({{site.baseurl}}/rancher/latest/en/) and be used as the OS to [add hosts]({{site.baseurl}}/rancher/latest/en/hosts/custom) to Rancher. + +### Launching Agents using Cloud-Config + +You can easily add hosts into Rancher by using [cloud-config]({{page.osbaseurl}}/configuration/#cloud-config) to launch the rancher/agent container. + +After Rancher is launched and [host registration]({{site.baseurl}}/rancher/latest/en/configuration/settings/#host-registration) has been saved, you will be able to find the [custom command]({{site.baseurl}}/rancher/latest/en/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://:8080/v1/projects/1a5/scripts/ +``` + +
+ +> **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://:8080/v1/projects/1a5/scripts/ + privileged: true + volumes: + - /var/run/docker.sock:/var/run/docker.sock +``` +
+ +> **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/latest/en/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/latest/en/cattle/scheduling/) and create a whitelist or blacklist of hosts for your [services]({{site.baseurl}}/rancher/latest/en/cattle/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://:8080/v1/projects/1a5/scripts/ + +# 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://:8080/v1/projects/1a5/scripts/ +``` + +#### Cloud-Config Example + +Adding one host label + +```yaml +#cloud-config +rancher: + services: + rancher-agent1: + image: rancher/agent:v0.8.2 + command: http://:8080/v1/projects/1a5/scripts/ + privileged: true + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + CATTLE_HOST_LABELS: foo=bar +``` +
+ +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://:8080/v1/projects/1a5/scripts/ + privileged: true + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + CATTLE_HOST_LABELS: foo=bar&hello=world +``` diff --git a/content/os/about/security/_index.md b/content/os/about/security/_index.md new file mode 100644 index 00000000000..a7f42ac613c --- /dev/null +++ b/content/os/about/security/_index.md @@ -0,0 +1,40 @@ +--- +tag: ["rancheros", "os", "security"] +category: "os" +layout: list-docs +title: RancherOS Security +weight: 303 +--- + +## RancherOS Security +--- + + + + + + + + +
+

Security policy

+

Rancher Labs supports responsible disclosure, and endeavours to resolve all issues in a reasonable time frame. RancherOS is a minimal Linux distribution, built with entirely using open source components.

+		 +

Reporting process

+

Please submit possible security issues by emailing security@rancher.com

+		 +

Announcments

+

Subscribe to the Rancher announcements forum for release updates.

+
+ +### RancherOS Vulnerabilities + +| ID | Description | Date | Resolution | +|----|-------------|------|------------| +| [CVE-2017-6074](http://seclists.org/oss-sec/2017/q1/471) | Local privilege-escalation using a user after free issue in [Datagram Congestion Control Protocol (DCCP)](https://wiki.linuxfoundation.org/networking/dccp). DCCP is built into the RancherOS kernel as a dynamically loaded module, and isn't loaded by default. | 17 Feb 2017 | [RancherOS v0.8.1](https://github.com/rancher/os/releases/tag/v0.8.1) using a [patched 4.9.12 Linux kernel](https://github.com/rancher/os-kernel/releases/tag/v4.9.12-rancher) | +| [CVE-2017-7184](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-7184) | Allows local users to obtain root privileges or cause a denial of service (heap-based out-of-bounds access) by leveraging the CAP_NET_ADMIN capability. | 3 April 2017 | [RancherOS v0.9.2-rc1](https://github.com/rancher/os/releases/tag/v0.9.2-rc1) using Linux 4.9.20 | +| [CVE-2017-1000364](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1000364) | Linux Kernel is prone to a local memory-corruption vulnerability. Attackers may be able to exploit this issue to execute arbitrary code with elevated privileges | 19 June 2017 | [RancherOS v1.0.3](https://github.com/rancher/os/releases/tag/v1.0.3) | +| [CVE-2017-1000366](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1000366) | glibc contains a vulnerability that allows manipulation of the heap/stack. Attackers may be able to exploit this issue to execute arbitrary code with elevated privileges | 19 June 2017 | [RancherOS v1.0.3](https://github.com/rancher/os/releases/tag/v1.0.3) | +| [CVE-2017-1000405](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-1000405) | The Linux Kernel versions 2.6.38 through 4.14 have a problematic use of pmd_mkdirty() in the touch_pmd() function inside the THP implementation. touch_pmd() can be reached by get_user_pages(). In such case, the pmd will become dirty. | 10 Dec 2017 | [RancherOS v1.1.1](https://github.com/rancher/os/releases/tag/v1.1.1) | +| [CVE-2017-5754](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5754) | Systems with microprocessors utilizing speculative execution and indirect branch prediction may allow unauthorized disclosure of information to an attacker with local user access via a side-channel analysis of the data cache. | 5 Jan 2018 | [RancherOS v1.1.3](https://github.com/rancher/os/releases/tag/v1.1.3) using Linux v4.9.75| +| [CVE-2017-5715](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715) | Systems with microprocessors utilizing speculative execution and indirect branch prediction may allow unauthorized disclosure of information to an attacker with local user access via a side-channel analysis | 6 Feb 2018 | [RancherOS v1.1.4](https://github.com/rancher/os/releases/tag/v1.1.4) using Linux v4.9.78 with the Retpoline support | diff --git a/content/os/five/_index.md b/content/os/five/_index.md deleted file mode 100644 index a7142a335d5..00000000000 --- a/content/os/five/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: Five - weight: 5 ---- - - -hello diff --git a/content/os/five/five-placeholder.md b/content/os/five/five-placeholder.md deleted file mode 100644 index 78df709eafb..00000000000 --- a/content/os/five/five-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder ---- - -# Five tasks placeholder md diff --git a/content/os/four/_index.md b/content/os/four/_index.md deleted file mode 100644 index 12040318cf5..00000000000 --- a/content/os/four/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: Four - weight: 4 ---- - - -hello diff --git a/content/os/four/four-placeholder.md b/content/os/four/four-placeholder.md deleted file mode 100644 index dd22142b087..00000000000 --- a/content/os/four/four-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder ---- - -# four tasks placeholder md diff --git a/content/os/installation/amazon-ecs/_index.md b/content/os/installation/amazon-ecs/_index.md new file mode 100644 index 00000000000..314f92c9dba --- /dev/null +++ b/content/os/installation/amazon-ecs/_index.md @@ -0,0 +1,85 @@ +--- +tag: ["rancheros", "os", "custom", "console"] +category: "os" +layout: list-docs +title: Amazon ECS (EC2 Container Service) +weight: 190 +--- + +## 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]({{page.osbaseurl}}/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]({{page.osbaseurl}}/configuration/#cloud-config) file. + +```yaml +#cloud-config +rancher: + environment: + ECS_CLUSTER: your-ecs-cluster-name + # Note: You will need to add this variable, if using awslogs for ECS task. + ECS_AVAILABLE_LOGGING_DRIVERS: |- + ["json-file","awslogs"] +# 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]({{page.osbaseurl}}/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 +``` + +
+ +> **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: [v1.2.0](https://github.com/rancher/os/releases/tag/v1.2.0) + +Region | Type | AMI +---|--- | --- +ap-south-1 | HVM - ECS enabled | [ami-add487c2](https://ap-south-1.console.aws.amazon.com/ec2/home?region=ap-south-1#launchInstanceWizard:ami=ami-add487c2) +eu-west-3 | HVM - ECS enabled | [ami-f1a3158c](https://eu-west-3.console.aws.amazon.com/ec2/home?region=eu-west-3#launchInstanceWizard:ami=ami-f1a3158c) +eu-west-2 | HVM - ECS enabled | [ami-8fbd58e8](https://eu-west-2.console.aws.amazon.com/ec2/home?region=eu-west-2#launchInstanceWizard:ami=ami-8fbd58e8) +eu-west-1 | HVM - ECS enabled | [ami-f41e768d](https://eu-west-1.console.aws.amazon.com/ec2/home?region=eu-west-1#launchInstanceWizard:ami=ami-f41e768d) +ap-northeast-2 | HVM - ECS enabled | [ami-3da30153](https://ap-northeast-2.console.aws.amazon.com/ec2/home?region=ap-northeast-2#launchInstanceWizard:ami=ami-3da30153) +ap-northeast-1 | HVM - ECS enabled | [ami-31c1b657](https://ap-northeast-1.console.aws.amazon.com/ec2/home?region=ap-northeast-1#launchInstanceWizard:ami=ami-31c1b657) +sa-east-1 | HVM - ECS enabled | [ami-31115f5d](https://sa-east-1.console.aws.amazon.com/ec2/home?region=sa-east-1#launchInstanceWizard:ami=ami-31115f5d) +ca-central-1 | HVM - ECS enabled | [ami-bba622df](https://ca-central-1.console.aws.amazon.com/ec2/home?region=ca-central-1#launchInstanceWizard:ami=ami-bba622df) +ap-southeast-1 | HVM - ECS enabled | [ami-aa5b1ad6](https://ap-southeast-1.console.aws.amazon.com/ec2/home?region=ap-southeast-1#launchInstanceWizard:ami=ami-aa5b1ad6) +ap-southeast-2 | HVM - ECS enabled | [ami-eec73c8c](https://ap-southeast-2.console.aws.amazon.com/ec2/home?region=ap-southeast-2#launchInstanceWizard:ami=ami-eec73c8c) +eu-central-1 | HVM - ECS enabled | [ami-29422646](https://eu-central-1.console.aws.amazon.com/ec2/home?region=eu-central-1#launchInstanceWizard:ami=ami-29422646) +us-east-1 | HVM - ECS enabled | [ami-84171efe](https://us-east-1.console.aws.amazon.com/ec2/home?region=us-east-1#launchInstanceWizard:ami=ami-84171efe) +us-east-2 | HVM - ECS enabled | [ami-9982b7fc](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#launchInstanceWizard:ami=ami-9982b7fc) +us-west-1 | HVM - ECS enabled | [ami-c7b3bca7](https://us-west-1.console.aws.amazon.com/ec2/home?region=us-west-1#launchInstanceWizard:ami=ami-c7b3bca7) +us-west-2 | HVM - ECS enabled | [ami-3924a041](https://us-west-2.console.aws.amazon.com/ec2/home?region=us-west-2#launchInstanceWizard:ami=ami-3924a041) diff --git a/content/os/installation/boot-process/built-in-system-services/_index.md b/content/os/installation/boot-process/built-in-system-services/_index.md new file mode 100644 index 00000000000..d6ff2b5f03c --- /dev/null +++ b/content/os/installation/boot-process/built-in-system-services/_index.md @@ -0,0 +1,54 @@ +--- +title: Built-in System Services in RancherOS + +redirect_from: + - os/v1.0/en/system-services/built-in-system-services/ + - os/v1.1/en/system-services/built-in-system-services/ + +--- + +## 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]({{page.osbaseurl}}/system-services/) or override services in the cloud-config. + +### preload-user-images + +Read more about [image preloading]({{page.osbaseurl}}/boot-process/image-preloading/). + +### network + +During this service, networking is set up, e.g. hostname, interfaces, and DNS. + +It is configured by `hostname` and `rancher.network`[settings]({{page.osbaseurl}}/networking/) in [cloud-config]({{page.osbaseurl}}/configuration/#cloud-config). + +### ntp + +Runs `ntpd` in a System Docker container. + +### 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=` kernel parameter exists, it sets `` 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]({{page.osbaseurl}}/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]({{page.osbaseurl}}/configuration/ssh-keys/) and metadata. + * Writes files specified by the `write_files` [cloud-config]({{page.osbaseurl}}/configuration/write-files/) setting. + * Resizes the device specified by the `rancher.resize_device` [cloud-config]({{page.osbaseurl}}/configuration/resizing-device-partition/) setting. + * Mount devices specified in the `mounts` [cloud-config]({{page.osbaseurl}}/configuration/additional-mounts/) setting. + * Set sysctl parameters specified in the`rancher.sysctl` [cloud-config]({{page.osbaseurl}}/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`). diff --git a/content/os/installation/boot-process/cloud-init/_index.md b/content/os/installation/boot-process/cloud-init/_index.md new file mode 100644 index 00000000000..b2070ec71ca --- /dev/null +++ b/content/os/installation/boot-process/cloud-init/_index.md @@ -0,0 +1,30 @@ +--- +tag: ["rancheros", "os", "cloud-init"] +category: "os" +layout: list-docs +title: Cloud-Init +weight: 151 +--- + +## Cloud-init + +Userdata and metadata can be fetched from a cloud provider, VM runtime, or management service during the RancherOS boot process. Since v0.8.0, this process occurs while RancherOS is still running from memory and before System Docker starts. It is configured by the `rancher.cloud_init.datasources` configuration parameter. For cloud-provider specific images, such as AWS and GCE, the datasource is pre-configured. + +### Userdata + +Userdata is a file given by users when launching RancherOS hosts. It is stored in different locations depending on its format. If the userdata is a [cloud-config]({{page.osbaseurl}}/configuration/#cloud-config) file, indicated by beginning with `#cloud-config` and being in YAML format, it is stored in `/var/lib/rancher/conf/cloud-config.d/boot.yml`. If the userdata is a script, indicated by beginning with `#!`, it is stored in `/var/lib/rancher/conf/cloud-config-script`. + +### Metadata + +Although the specifics vary based on provider, a metadata file will typically contain information about the RancherOS host and contain additional configuration. Its primary purpose within RancherOS is to provide an alternate source for SSH keys and hostname configuration. For example, AWS launches hosts with a set of authorized keys and RancherOS obtains these via metadata. Metadata is stored in `/var/lib/rancher/conf/metadata`. + +## Configuration Load Order + +[Cloud-config]({{page.osbaseurl}}/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. diff --git a/content/os/installation/boot-process/image-preloading/_index.md b/content/os/installation/boot-process/image-preloading/_index.md new file mode 100644 index 00000000000..546a5c296a2 --- /dev/null +++ b/content/os/installation/boot-process/image-preloading/_index.md @@ -0,0 +1,24 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Image Preloading +weight: 152 +--- + +## Image Preloading +--- + +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 (`.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). diff --git a/content/os/installation/boot-process/logging/_index.md b/content/os/installation/boot-process/logging/_index.md new file mode 100644 index 00000000000..653785a3af0 --- /dev/null +++ b/content/os/installation/boot-process/logging/_index.md @@ -0,0 +1,46 @@ +--- +tag: ["rancheros", "os", "logging"] +category: "os" +layout: list-docs +title: System Logging +weight: 153 +--- + +## RancherOS System Logging + +### System services + +RancherOS uses containers for its system services. This means the logs for `syslog`, `acipd`, `system-cron`, `udev`, `network`, `ntp`, `console` and the user Docker are available using `sudo ros service logs `. + +### Boot logging + +Since v1.1.0, the init process's logs are copied to `/var/log/boot` after the user-space filesystem is made available. These can be used to diagnose initialisation, network, and cloud-init issues. + +### Remote Syslog logging + +The Linux kernel has a `netconsole` logging facility that allows it to send the Kernel level logs to a remote Syslog server. +When you set this kernel boot parameter in RancherOS v1.1.0 and later, the RancherOS debug logs will also be sent to it. + +To set up Linux kernel and RancherOS remote Syslog logging, you need to set both a local, and remote host IP address - even if this address isn't the final IP address of your system. The kernel setting looks like: + +``` + netconsole=[+][src-port]@[src-ip]/[],[tgt-port]@/[tgt-macaddr] + + where + + if present, enable extended console support + src-port source for UDP packets (defaults to 6665) + src-ip source IP to use (interface address) + dev network interface (eth0) + tgt-port port for logging agent (6666) + tgt-ip IP address for logging agent + tgt-macaddr ethernet MAC address for logging agent (broadcast) +``` + +For example, on my current test system, I have set the kernel boot line to: + + +``` +printk.devkmsg=on console=tty1 rancher.autologin=tty1 console=ttyS0 rancher.autologin=ttyS0 rancher.state.dev=LABEL=RANCHER_STATE rancher.state.autoformat=[/dev/sda,/dev/vda] rancher.rm_usr loglevel=8 netconsole=+9999@10.0.2.14/,514@192.168.42.223/ +``` + +The kernel boot parameters can be set during installation using `sudo ros install --append "...."`, or on an installed RancherOS system, by running `sudo ros config syslinx` (which will start vi in a container, editing the `global.cfg` boot config file. diff --git a/content/os/installation/configuration/_index.md b/content/os/installation/configuration/_index.md new file mode 100644 index 00000000000..64717d9b584 --- /dev/null +++ b/content/os/installation/configuration/_index.md @@ -0,0 +1,93 @@ +--- + tag: ["rancheros", "os", "configuration", "custom"] + category: "os" + layout: list-docs + title: Configuration + weight: 120 +--- + +## 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 `#!` (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 set ` command can be used. +For more complicated settings, like the [sysctl settings]({{page.osbaseurl}}/sysctl/), you can also create a small YAML file and then run `sudo ros config merge -i `. + +#### 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 +``` + +#### Validating a Configuration File + +To validate a configuration file you can use the `ros config validate` command. + +``` +$ sudo ros config validate -i cloud-config.yml +``` diff --git a/content/os/installation/configuration/adding-kernel-parameters/_index.md b/content/os/installation/configuration/adding-kernel-parameters/_index.md new file mode 100644 index 00000000000..2d0885f3a32 --- /dev/null +++ b/content/os/installation/configuration/adding-kernel-parameters/_index.md @@ -0,0 +1,68 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Adding Kernel Parameters +weight: 133 +--- + +## Kernel boot parameters + +RancherOS parses the Linux kernel boot cmdline to add any keys it understands to its configuration. This allows you to modify what cloud-init sources it will use on boot, to enable `rancher.debug` logging, or to almost any other configuration setting. + +There are two ways to set or modify persistent kernel parameters, in-place (editing the file and reboot) or during installation to disk. + +### In-place editing + +_As of v1.1+_ +To edit the kernel boot parameters of an already installed RancherOS system, use the new `sudo ros config syslinux` editing command (uses `vi`). + +> To activate this setting, you will need to reboot. + +_For v1.0_ + +For in-place editing, you will need to run a container with an editor and a mount to access the `/boot/global.cfg` file containing the kernel parameters. + +> To activate this setting, you will need to reboot. + +```bash +$ sudo system-docker run --rm -it -v /:/host alpine vi /host/boot/global.cfg +``` + +### During installation + +If you want to set the extra kernel parameters when you are [Installing RancherOS to Disk]({{page.osbaseurl}}/running-rancheros/server/install-to-disk/) please use the `--append` parameter. + +```bash +$ sudo ros install -d /dev/sda --append "rancheros.autologin=tty1" +``` + +_As of v1.1_ + +### Graphical boot screen + +RancherOS v1.1.0 added a Syslinux boot menu, which allows you to temporarily edit the boot paramters, or to select "Debug logging", "Autologin", both "Debug logging & Autologin" and "Recovery Console". + +On desktop systems the Syslinux boot menu can be switched to graphical mode by adding `UI vesamenu.c32` to a new line in `global.cfg` (use `sudo ros config syslinux` to edit the file). + +### Useful RancherOS cloud-init or boot settings + +#### Recovery console + +`rancher.recovery=true` will start a single user `root` bash session as easily in the boot process, with no network, or persitent filesystem mounted. This can be used to fix disk problems, or to debug your system. + +#### Enable/Disable sshd + +`rancher.ssh.daemon=false` (its enabled in the os-config) can be used to start your RancherOS with no sshd daemon. This can be used to further reduce the ports that your system is listening on. + +#### Enable debug logging + +`rancher.debug=true` will log everything to the console for debugging. + +#### Autologin console + +`rancher.autologin=` will automatically log in the sepcified console - common values are `tty1`, `ttyS0` and `ttyAMA0` - depending on your platform. + +#### Enable/Disable hypervisor service auto-enable + +RancherOS v1.1.0 added detection of Hypervisor, and then will try to download the a service called `-vm-tools`. This may cause boot speed issues, and so can be disabled by setting `rancher.hypervisor_service=false`. diff --git a/content/os/installation/configuration/docker/_index.md b/content/os/installation/configuration/docker/_index.md new file mode 100644 index 00000000000..7c5e87831b9 --- /dev/null +++ b/content/os/installation/configuration/docker/_index.md @@ -0,0 +1,137 @@ +--- +tag: ["rancheros", "os", "docker", "system docker"] +category: "os" +layout: list-docs +title: Configuring Docker or System Docker +weight: 126 +--- + +## Configuring Docker or System Docker +--- + +In RancherOS, you can configure System Docker and Docker daemons by using [cloud-config]({{page.osbaseurl}}/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 +``` + +#### User Docker settings + +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` | List +`insecure_registry` | List +`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]({{page.osbaseurl}}/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. + +#### Example using extra_args for setting MTU + +The following example can be used to set MTU on the Docker daemon: + +```yaml +#cloud-config +rancher: + docker: + extra_args: [--mtu, 1460] +``` + +### 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 +``` + +#### System Docker settings + +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) | `[]` | + +### Using a pull through registry mirror + +There are 3 Docker engines that can be configured to use the pull-through Docker Hub registry mirror cache: + +``` +#cloud-config +rancher: + bootstrap_docker: + registry_mirror: "http://10.10.10.23:5555" + docker: + registry_mirror: "http://10.10.10.23:5555" + system_docker: + registry_mirror: "http://10.10.10.23:5555" +``` + +`bootstrap_docker` is used to prepare and initial network and pull any cloud-config options that can be used to configure the final network configuration and System-docker - its very unlikely to pull any images. + +A successful pull through mirror cache request by System-docker looks like: + +``` +[root@rancher-dev rancher]# system-docker pull alpine +Using default tag: latest +DEBU[0201] Calling GET /v1.23/info +> WARN[0201] Could not get operating system name: Error opening /usr/lib/os-release: open /usr/lib/os-release: no such file or directory +WARN[0201] Could not get operating system name: Error opening /usr/lib/os-release: open /usr/lib/os-release: no such file or directory +DEBU[0201] Calling POST /v1.23/images/create?fromImage=alpine%3Alatest +DEBU[0201] hostDir: /etc/docker/certs.d/10.10.10.23:5555 +DEBU[0201] Trying to pull alpine from http://10.10.10.23:5555/ v2 +DEBU[0204] Pulling ref from V2 registry: alpine:latest +DEBU[0204] pulling blob "sha256:2aecc7e1714b6fad58d13aedb0639011b37b86f743ba7b6a52d82bd03014b78e" latest: Pulling from library/alpine +DEBU[0204] Downloaded 2aecc7e1714b to tempfile /var/lib/system-docker/tmp/GetImageBlob281102233 2aecc7e1714b: Extracting 1.99 MB/1.99 MB +DEBU[0204] Untar time: 0.161064213s +DEBU[0204] Applied tar sha256:3fb66f713c9fa9debcdaa58bb9858bd04c17350d9614b7a250ec0ee527319e59 to 841c99a5995007d7a66b922be9bafdd38f8090af17295b4a44436ef433a2aecc7e1714b: Pull complete +Digest: sha256:0b94d1d1b5eb130dd0253374552445b39470653fb1a1ec2d81490948876e462c +Status: Downloaded newer image for alpine:latest +``` diff --git a/content/os/installation/configuration/hostname/_index.md b/content/os/installation/configuration/hostname/_index.md new file mode 100644 index 00000000000..2fe00f409df --- /dev/null +++ b/content/os/installation/configuration/hostname/_index.md @@ -0,0 +1,17 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Setting the Hostname +weight: 124 +--- + +## Setting the Hostname +--- + +You can set the hostname of the host using [cloud-config]({baseurl}}/configuration/#cloud-config). The example below shows how to configure it. + +```yaml +#cloud-config +hostname: myhost +``` diff --git a/content/os/installation/configuration/kernel-modules-kernel-headers/_index.md b/content/os/installation/configuration/kernel-modules-kernel-headers/_index.md new file mode 100644 index 00000000000..88c0de7d598 --- /dev/null +++ b/content/os/installation/configuration/kernel-modules-kernel-headers/_index.md @@ -0,0 +1,43 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Installing Kernel Modules with Kernel Headers +weight: 135 +--- + +## 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 kernel-headers +``` + +#### System Docker + +``` +$ sudo ros service enable kernel-headers-system-docker +$ sudo ros service up 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 +``` diff --git a/content/os/installation/configuration/loading-kernel-modules/_index.md b/content/os/installation/configuration/loading-kernel-modules/_index.md new file mode 100644 index 00000000000..b97052b4df5 --- /dev/null +++ b/content/os/installation/configuration/loading-kernel-modules/_index.md @@ -0,0 +1,87 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Loading Extra Kernel Modules +weight: 134 +--- + +Since RancherOS v0.8, we build our own kernels using an unmodified kernel.org LTS kernel. +We also build almost all optional extras as modules - so most in-tree modules are available +in the `kernel-extras` service. + + +If you do need to build kernel modules for RancherOS, there are 3 options: + +0 Try the `kernel-extras` service +1 Ask us to add it into the next release +2 If its out of tree, copy the methods used for the zfs and open-iscsi services +3 Build it yourself. + +## Try the kernel-extras service + +We build the RancherOS kernel with most of the optional drivers as kernel modules, packaged +into an optional RancherOS service. + +To install these, run: + +``` +sudo ros service enable kernel-extras +sudo ros service up kernel-extras +``` + +The modules should now be available for you to `modprobe` + +## Ask us to do it + +Open a GitHub issue in the https://github.com/rancher/os repository - we'll probably add +it to the kernel-extras next time we build a kernel. Tell us if you need the module at initial +configuration or boot, and we can add it to the default kernel modules. + +## Copy the out of tree build method + +See https://github.com/rancher/os-services/blob/master/z/zfs.yml and +https://github.com/rancher/os-services/tree/master/images/20-zfs + +The build container and build.sh script build the source, and then create a tools image, which is used to +"wonka.sh" import those tools into the console container using `docker run` + + +## Build your own. + +As an example I'm going build the `intel-ishtp` hid driver using the `rancher/os-zfs:` images to build in, as they should contain the right tools versions for that kernel. + + +``` +sudo docker run --rm -it --privileged -v $(pwd):/data -w /data rancher/os-zfs:$(ros -v | cut -d ' ' -f 3) bash + +apt-get update +apt-get install -qy libncurses5-dev bc libssh-dev +curl -SsL -o src.tgz https://github.com/rancher/os-kernel/releases/download/v$(uname -r)/linux-$(uname -r)-src.tgz +tar zxvf src/tgz +zcat /proc/config.gz >.config +# Yes, ignore the name of the directory :/ +cd v* +# enable whatever modules you want to add. +make menuconfig +# I finally found an Intel sound hub that wasn't enabled yet +# CONFIG_INTEL_ISH_HID=m +make modules SUBDIRS=drivers/hid/intel-ish-hid + +# test it +insmod drivers/hid/intel-ish-hid/intel-ishtp.ko +rmmod intel-ishtp + +# install it +cp drivers/hid/intel-ish-hid/*.ko /lib/modules/4.9.45-rancher/kernel/drivers/hid/ +depmod + +# done +exit +``` + +Then in your console, you should be able to run + +``` +modprobe intel-ishtp +``` diff --git a/content/os/installation/configuration/private-registries/_index.md b/content/os/installation/configuration/private-registries/_index.md new file mode 100644 index 00000000000..ae9019b9935 --- /dev/null +++ b/content/os/installation/configuration/private-registries/_index.md @@ -0,0 +1,98 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Private Registries +weight: 128 +--- + +## Private Registries +--- + +When launching services through a [cloud-config]({{page.osbaseurl}}/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]({{page.osbaseurl}}/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----- +``` diff --git a/content/os/installation/configuration/resizing-device-partition/_index.md b/content/os/installation/configuration/resizing-device-partition/_index.md new file mode 100644 index 00000000000..af2b4d70ea5 --- /dev/null +++ b/content/os/installation/configuration/resizing-device-partition/_index.md @@ -0,0 +1,22 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Resizing a Device Partition +weight: 131 +--- + +## Resizing a Device Partition +--- + +The `resize_device` cloud config option can be used to automatically extend the first partition (assuming its `ext4`) to fill the size of it's device. + +Once the partition has been resized to fill the device, a `/var/lib/rancher/resizefs.done` file will be written to prevent the resize tools from being run again. If you need it to run again, delete that file and reboot. + +```yaml +#cloud-config +rancher: + resize_device: /dev/sda +``` + +This behavior is the default when launching RancherOS on AWS. diff --git a/content/os/installation/configuration/running-commands/_index.md b/content/os/installation/configuration/running-commands/_index.md new file mode 100644 index 00000000000..4d5dbdc2d9b --- /dev/null +++ b/content/os/installation/configuration/running-commands/_index.md @@ -0,0 +1,53 @@ +--- +tag: ["rancheros", "os", "commands"] +category: "os" +layout: list-docs +title: Running Commands +weight: 123 +--- + +## Running Commands +--- + +You can automate running commands on boot using the `runcmd` cloud-config directive. Commands can be specified as either a list or a string. In the latter case, the command is executed with `sh`. + +```yaml +#cloud-config +runcmd: +- [ touch, /home/rancher/test1 ] +- echo "test" > /home/rancher/test2 +``` + +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]({{page.osbaseurl}}/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. + +```yaml +#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]({{page.osbaseurl}}/system-services/adding-system-services/) is recommended. + +## Running Commands Early in the Boot Process +--- + +The `bootcmd` parameter can be used to run commands earlier in the boot process. In particular, `bootcmd` will be executed while RancherOS is still running from memory and before System Docker and any system services are started. + +The syntax for bootcmd is the same as `runcmd`. + +```yaml +#cloud-config +bootcmd: +- [ mdadm, --assemble, --scan ] +``` diff --git a/content/os/installation/configuration/setting-up-docker-tls/_index.md b/content/os/installation/configuration/setting-up-docker-tls/_index.md new file mode 100644 index 00000000000..f6143ba0c16 --- /dev/null +++ b/content/os/installation/configuration/setting-up-docker-tls/_index.md @@ -0,0 +1,61 @@ +--- +tag: ["rancheros", "os", "docker", "tls"] +category: "os" +layout: list-docs +title: Setting up Docker TLS +weight: 127 +--- + +## 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 -H ... -H +$ sudo system-docker restart docker +``` + +Here, ``s are the hostnames that you will be able to use as your docker host names. A `` 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://:2376 DOCKER_TLS_VERIFY=1 +$ docker ps +``` diff --git a/content/os/installation/configuration/ssh-keys/_index.md b/content/os/installation/configuration/ssh-keys/_index.md new file mode 100644 index 00000000000..900759d0bcb --- /dev/null +++ b/content/os/installation/configuration/ssh-keys/_index.md @@ -0,0 +1,27 @@ +--- +tag: ["rancheros", "os", "ssh"] +category: "os" +layout: list-docs +title: SSH Keys +weight: 121 +--- + +## SSH Keys +--- + +RancherOS supports adding SSH keys through the [cloud-config]({{page.osbaseurl}}/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@ +``` + +Please note that OpenSSH 7.0 and greater similarly disable the ssh-dss (DSA) public key algorithm. It too is weak and we recommend against its use. diff --git a/content/os/installation/configuration/switching-consoles/_index.md b/content/os/installation/configuration/switching-consoles/_index.md new file mode 100644 index 00000000000..0e3aafe78fc --- /dev/null +++ b/content/os/installation/configuration/switching-consoles/_index.md @@ -0,0 +1,141 @@ +--- +tag: ["rancheros", "os", "consoles"] +category: "os" +layout: list-docs +title: Switching Consoles +weight: 125 +--- + +## Switching Consoles +--- + +When [booting from the ISO]({{page.osbaseurl}}/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]({{page.osbaseurl}}/configuration/#cloud-config). + +### Enabling Consoles using Cloud-Config + +When launching RancherOS with a [cloud-config]({{page.osbaseurl}}/configuration/#cloud-config) file, you can select which console you want to use. + +Currently, the list of available consoles are: + +* default +* alpine +* 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 alpine +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. +``` + +
+ +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 +``` + +
+ +> **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 +``` + +
+ +> **Note:** When using a persistent console and in the current version's console, [rolling back]({{page.osbaseurl}}/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 +``` + +
+ +At the next reboot, RancherOS will be using the Debian console. diff --git a/content/os/installation/configuration/switching-docker-versions/_index.md b/content/os/installation/configuration/switching-docker-versions/_index.md new file mode 100644 index 00000000000..d2b47ba324b --- /dev/null +++ b/content/os/installation/configuration/switching-docker-versions/_index.md @@ -0,0 +1,100 @@ +--- +tag: ["rancheros", "os", "docker"] +category: "os" +layout: list-docs +title: Switching Docker Versions +weight: 129 +--- + +## Changing Docker Versions + +The version of User Docker used in RancherOS can be configured using a [cloud-config]({{page.osbaseurl}}/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 +``` + +## Using a Custom Version of Docker + +If you're using a version of Docker that isn't available by default or a custom build of Docker then you can create a custom Docker image and service file to distribute it. + +Docker engine images are built by adding the binaries to a folder named `engine` and then adding this folder to a `FROM scratch` image. For example, the following Dockerfile will build a Docker engine image. + +``` +FROM scratch +COPY engine /engine +``` + +Once the image is built a [system service]({{page.osbaseurl}}/system-services/adding-system-services/) configuration file must be created. An [example file](https://github.com/rancher/os-services/blob/master/d/docker-1.12.3.yml) can be found in the rancher/os-services repo. Change the `image` field to point to the Docker engine image you've built. + +All of the previously mentioned methods of switching Docker engines are now available. For example, if your service file is located at `https://myservicefile` then the following cloud-config file could be used to use your custom Docker engine. + +```yaml +#cloud-config +rancher: + docker: + engine: https://myservicefile +``` diff --git a/content/os/installation/configuration/sysctl/_index.md b/content/os/installation/configuration/sysctl/_index.md new file mode 100644 index 00000000000..5fb072b0151 --- /dev/null +++ b/content/os/installation/configuration/sysctl/_index.md @@ -0,0 +1,21 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: sysctl Settings +weight: 132 +--- + +## 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 +``` + +You can either add these settings to your `cloud-init.yml`, or use `sudo ros config merge -i somefile.yml` to merge settings into your existing system. diff --git a/content/os/installation/configuration/users/_index.md b/content/os/installation/configuration/users/_index.md new file mode 100644 index 00000000000..286dab38d63 --- /dev/null +++ b/content/os/installation/configuration/users/_index.md @@ -0,0 +1,17 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Users +weight: 130 +--- + +## 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]({{page.osbaseurl}}/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. diff --git a/content/os/installation/configuration/write-files/_index.md b/content/os/installation/configuration/write-files/_index.md new file mode 100644 index 00000000000..8d237003c94 --- /dev/null +++ b/content/os/installation/configuration/write-files/_index.md @@ -0,0 +1,47 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Writing Files +weight: 122 +--- + +## 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] +``` diff --git a/content/os/installation/custom-builds/custom-console/_index.md b/content/os/installation/custom-builds/custom-console/_index.md new file mode 100644 index 00000000000..e8a4c61b177 --- /dev/null +++ b/content/os/installation/custom-builds/custom-console/_index.md @@ -0,0 +1,141 @@ +--- +tag: ["rancheros", "os", "custom", "console"] +category: "os" +layout: list-docs +title: Custom Console +weight: 180 +--- + +## Custom Console +--- + +When [booting from the ISO]({{page.osbaseurl}}/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]({{page.osbaseurl}}/configuration/#cloud-config). + +### Enabling Consoles using Cloud-Config + +When launching RancherOS with a [cloud-config]({baseurl}}/configuration/#cloud-config) file, you can select which console you want to use. + +Currently, the list of available consoles are: + +* default +* alpine +* 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 alpine +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. +``` + +
+ +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 +``` + +
+ +> **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 +``` + +
+ +> **Note:** When using a persistent console and in the current version's console, [rolling back]({{page.osbaseurl}}/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 +``` + +
+ +At the next reboot, RancherOS will be using the Debian console. diff --git a/content/os/installation/custom-builds/custom-kernels/_index.md b/content/os/installation/custom-builds/custom-kernels/_index.md new file mode 100644 index 00000000000..9bfefc594d7 --- /dev/null +++ b/content/os/installation/custom-builds/custom-kernels/_index.md @@ -0,0 +1,107 @@ +--- +tag: ["rancheros", "os", "custom", "kernels"] +category: "os" +layout: list-docs +title: Custom Kernels +weight: 181 +--- + +## Custom Kernels + +### Building and 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 `./Dockerfile.dapper` file, update the `KERNEL_TAG`, `KERNEL_VERSION`, `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. + + `./Dockerfile.dapper` file + + ```bash + ########## Kernel version Configuration ############################# + ENV KERNEL_TAG=v4.8.7 + ENV KERNEL_VERSION=4.8.7-rancher + ENV KERNEL_SHA1=5c10724a0e7e97b72046be841df0c69c6e2a03c2 + ENV KERNEL_URL=https://github.com/rancher/linux/archive/${KERNEL_TAG}.tar.gz + ``` + +3. After you've replaced the `KERNEL_*` values, 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 + ...snip... + --- 4.8.7-rancher Kernel prepared for RancherOS + ./dist/kernel/extra-linux-4.8.7-rancher-x86.tar.gz + ./dist/kernel/build-linux-4.8.7-rancher-x86.tar.gz + ./dist/kernel/linux-4.8.7-rancher-x86.tar.gz + ./dist/kernel/config + + Images ready to push: + rancher/os-extras:4.8.7-rancher + rancher/os-headers:4.8.7-rancher + + ``` + +Now you need to either upload the `./dist/kernel/linux-4.8.7-rancher-x86.tar.gz` file to somewhere, or copy that file into your clone of the `rancher/os` repo, as `assets/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 - which you will need to tag them with a different organisation name, push them to a registry, and create custom service.yml files. + +### Building a RancherOS release using the Packaged kernel files. + +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]({{page.osbaseurl}}/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 + ``` + +
+ + > **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: + + `.tar.gz` is the one KERNEL_URL should point to. It contains the kernel binary, core modules and firmware: + + ``` + boot/ + vmlinuz- + lib/ + modules/ + / + ... + firmware/ + ... + ``` + + `build.tar.gz` contains build headers to build additional modules: it is a subset of the kernel sources tarball. These files will be installed into `/usr/src/` 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/ + / + ... + firmware/ + ... + ``` + + 3. After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{page.osbaseurl}}/configuration/custom-rancheros-iso/). diff --git a/content/os/installation/custom-builds/custom-rancheros-iso/_index.md b/content/os/installation/custom-builds/custom-rancheros-iso/_index.md new file mode 100644 index 00000000000..769d441e64d --- /dev/null +++ b/content/os/installation/custom-builds/custom-rancheros-iso/_index.md @@ -0,0 +1,93 @@ +--- +tag: ["rancheros", "os", "custom", "iso"] +category: "os" +layout: list-docs +title: Custom RancherOS ISO +weight: 182 +--- + +## 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]({{page.osbaseurl}}/configuration/custom-kernels), or [custom Docker]({{page.osbaseurl}}/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]({{page.osbaseurl}}/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{page.osbaseurl}}/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.iso", + "iso_checksum": "", + "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-.tar.gz disk.raw +``` + +NOTE: the last command should be using GNU tar. It might be named `gtar` on your system. diff --git a/content/os/installation/networking/dns/_index.md b/content/os/installation/networking/dns/_index.md new file mode 100644 index 00000000000..1de82c3ab44 --- /dev/null +++ b/content/os/installation/networking/dns/_index.md @@ -0,0 +1,33 @@ +--- +tag: ["rancheros", "os", "networking", "dns"] +category: "os" +layout: list-docs +title: Configuring DNS +weight: 171 +--- + +## 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 +``` diff --git a/content/os/installation/networking/interfaces/_index.md b/content/os/installation/networking/interfaces/_index.md new file mode 100644 index 00000000000..937255425fc --- /dev/null +++ b/content/os/installation/networking/interfaces/_index.md @@ -0,0 +1,170 @@ +--- +tag: ["rancheros", "os", "networking", "interfaces"] +category: "os" +layout: list-docs +title: Configuring Network Interfaces +weight: 170 +--- + +## 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 +``` + +### Bridging + +In this example, you can create a bridge interface. + +``` +#cloud-config +rancher: + network: + interfaces: + br0: + bridge: true + dhcp: true + eth0: + bridge: br0 +``` + +### Run custom network configuration commands + +_As of v1.1_ + +You can configure `pre` and `post` network configuration commands to run in the `network` service container by adding `pre_cmds` and `post_cmds` array keys to `rancher.network`, or `pre_up` and`post_up` keys for specific `rancher.network.interfaces`. + +For example: + +``` +#cloud-config +write_files: + - container: network + path: /var/lib/iptables/rules.sh + permissions: "0755" + owner: root:root + content: | + #!/bin/bash + set -ex + echo $@ >> /var/log/net.log + # the last line of the file needs to be a blank line or a comment +rancher: + network: + dns: + nameservers: + - 8.8.4.4 + - 4.2.2.3 + pre_cmds: + - /var/lib/iptables/rules.sh pre_cmds + post_cmds: + - /var/lib/iptables/rules.sh post_cmds + interfaces: + lo: + pre_up: + - /var/lib/iptables/rules.sh pre_up lo + post_up: + - /var/lib/iptables/rules.sh post_up lo + eth0: + pre_up: + - /var/lib/iptables/rules.sh pre_up eth0 + post_up: + - /var/lib/iptables/rules.sh post_up eth0 + eth1: + dhcp: true + pre_up: + - /var/lib/iptables/rules.sh pre_up eth1 + post_up: + - /var/lib/iptables/rules.sh post_up eth1 + eth2: + address: 192.168.3.13/16 + mtu: 1450 + pre_up: + - /var/lib/iptables/rules.sh pre_up eth2 + post_up: + - /var/lib/iptables/rules.sh post_up eth2 +``` diff --git a/content/os/installation/networking/proxy-settings/_index.md b/content/os/installation/networking/proxy-settings/_index.md new file mode 100644 index 00000000000..cfe28ec896a --- /dev/null +++ b/content/os/installation/networking/proxy-settings/_index.md @@ -0,0 +1,39 @@ +--- +tag: ["rancheros", "os", "proxy"] +category: "os" +layout: list-docs +title: Configuring Proxy Settings +weight: 172 +--- + +## 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 +``` + +
+ +> **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 +``` diff --git a/content/os/installation/running-rancheros/_index.md b/content/os/installation/running-rancheros/_index.md new file mode 100644 index 00000000000..c5ef74be657 --- /dev/null +++ b/content/os/installation/running-rancheros/_index.md @@ -0,0 +1,39 @@ +--- +tag: ["rancheros", "os", "installation"] +category: "os" +layout: list-docs +title: Running RancherOS +weight: 100 +--- + +## 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]({{page.osbaseurl}}/quick-start-guide/). + +### Platforms + +#### Workstation + +[Docker Machine]({{page.osbaseurl}}/running-rancheros/workstation/docker-machine) + +[Boot from ISO]({{page.osbaseurl}}/running-rancheros/workstation/boot-from-iso) + + +#### Cloud + +[Amazon EC2]({{page.osbaseurl}}/running-rancheros/cloud/aws) + +[Google Compute Engine]({{page.osbaseurl}}/running-rancheros/cloud/gce) + +[DigitalOcean]({{page.osbaseurl}}/running-rancheros/cloud/do) + +[Azure]({{page.osbaseurl}}/running-rancheros/cloud/azure) + +#### Bare Metal & Virtual Servers + +[iPXE]({{page.osbaseurl}}/running-rancheros/server/ipxe) + +[PXE]({{page.osbaseurl}}/running-rancheros/server/pxe) + +[Install to Hard Disk]({{page.osbaseurl}}/running-rancheros/server/install-to-disk) diff --git a/content/os/installation/running-rancheros/cloud/aws/_index.md b/content/os/installation/running-rancheros/cloud/aws/_index.md new file mode 100644 index 00000000000..0850ba02fe4 --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/aws/_index.md @@ -0,0 +1,74 @@ +--- +tag: ["rancheros", "os", "amazon", "ec2"] +category: "os" +layout: list-docs +title: Amazon EC2 +weight: 105 +--- + +## 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]({{page.osbaseurl}}/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@ +``` + +If you have issues logging into RancherOS, try using this command to help debug the issue. + +``` +$ ssh -v -i /Directory/of/MySSHKeyName.pem rancher@ +``` + +## Latest AMI Releases + +Please check the [README](https://github.com/rancher/os/blob/master/README.md) in our RancherOS repository for our latest AMIs. diff --git a/content/os/installation/running-rancheros/cloud/azure/_index.md b/content/os/installation/running-rancheros/cloud/azure/_index.md new file mode 100644 index 00000000000..4e088e17f81 --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/azure/_index.md @@ -0,0 +1,34 @@ +--- +tag: ["rancheros", "os", "azure"] +category: "os" +layout: list-docs +title: Azure +weight: 110 +--- + +## 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@ -p 22 +``` diff --git a/content/os/installation/running-rancheros/cloud/do/_index.md b/content/os/installation/running-rancheros/cloud/do/_index.md new file mode 100644 index 00000000000..f1f4a94a0d3 --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/do/_index.md @@ -0,0 +1,53 @@ +--- +tag: ["rancheros", "os", "digitalocean"] +category: "os" +layout: list-docs +title: Digital Ocean +weight: 107 + +## Running RancherOS in DigitalOcean +--- + +Running RancherOS on DigitalOcean is not yet supported, but there is a `rancheros` image now available from the commandline tools, so you can run: + +``` +$ doctl.exe compute droplet create --image rancheros --region sfo1 --size 2gb --ssh-keys 0a:db:77:92:03:b5:b2:94:96:d0:92:6a:e1:da:cd:28 myrancherosvm +ID Name Public IPv4 Private IPv4 Public IPv6 Memory VCPUs Disk Region Image Status Tags +47145723 myrancherosvm 2048 2 40 sfo1 RacherOS v1.0.1-rc [UNSUPPORTED/BETA] new + +$ doctl.exe compute droplet list +47145723 myrancherosvm 107.170.203.111 10.134.26.83 2604:A880:0001:0020:0000:0000:2750:0001 2048 2 40 sfo1 RacherOS v1.0.1-rc [UNSUPPORTED/BETA] active + +ssh -i ~/.ssh/Sven.pem rancher@107.170.203.111 +``` + +or use `docker-machine`: + +``` +$ docker-machine create -d digitalocean --digitalocean-access-token --digitalocean-image rancheros --digitalocean-region sfo1 --digitalocean-size 2gb --digitalocean-ssh-user rancher sven-machine +Running pre-create checks... +Creating machine... +(sven-machine) Creating SSH key... +(sven-machine) Assuming Digital Ocean private SSH is located at ~/.ssh/id_rsa +(sven-machine) Creating Digital Ocean droplet... +(sven-machine) Waiting for IP address to be assigned to the Droplet... +Waiting for machine to be running, this may take a few minutes... +Detecting operating system of created instance... +Waiting for SSH to be available... +Detecting the provisioner... +Provisioning with rancheros... +Copying certs to the local machine directory... +Copying certs to the remote machine... +Setting Docker configuration on the remote daemon... +Checking connection to Docker... +Docker is up and running! +To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: C:\Users\svend\src\github.com\docker\machine\machine.exe env sven-machine +$ docker-machine ls +NAME ACTIVE DRIVER STATE URL SWARM DOCKER ERRORS +rancheros-100 - virtualbox Stopped Unknown +sven-machine - digitalocean Running tcp://104.131.156.5:2376 v17.03.1-ce +$ docker-machine ssh sven-machine +Enter passphrase for key '/c/Users/svend/.ssh/id_rsa': +[rancher@sven-machine ~]$ +[rancher@sven-machine ~]$ +``` diff --git a/content/os/installation/running-rancheros/cloud/gce/_index.md b/content/os/installation/running-rancheros/cloud/gce/_index.md new file mode 100644 index 00000000000..a8fc903d298 --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/gce/_index.md @@ -0,0 +1,151 @@ +--- +tag: ["rancheros", "os", "gce"] +category: "os" +layout: list-docs +title: Google Cloud Engine (GCE) +weight: 106 +--- + +## Running RancherOS on Google Compute Engine (GCE) +---- + +> **Note:** Due to the maximum transmission unit (MTU) of [1460 bytes on GCE](https://cloud.google.com/compute/docs/troubleshooting#packetfragmentation), you will need to configure your [network interfaces]({{site.baseurl}}/os/networking/interfaces/) and both the [Docker and System Docker]({{site.baseurl}}/os/configuration/docker/) to use a MTU of 1460 bytes or you will encounter weird networking related errors. + +### 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 --zone --image +``` + +### 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]({{page.osbaseurl}}/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 --zone --image --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 --metadata-from-file user-data=/Directory/of/File --project --zone +Updated [https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE_OF_INSTANCE/instances/INSTANCE_NAME]. +$ gcloud compute instances reset --project --zone +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 --project --zone +``` + +**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 --project --zone --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 --project --zone +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@ --project --zone +``` + +If you have issues logging into RancherOS, try using this command to help debug the instance. + +``` +$ gcloud compute instances get-serial-port-output --zone --project +``` diff --git a/content/os/installation/running-rancheros/cloud/openstack/_index.md b/content/os/installation/running-rancheros/cloud/openstack/_index.md new file mode 100644 index 00000000000..f5061193d5c --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/openstack/_index.md @@ -0,0 +1,15 @@ +--- +tag: ["rancheros", "os", "openstack"] +category: "os" +layout: list-docs +title: OpenStack +weight: 109 + +--- + +## 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]({{page.osbaseurl}}/configuration/#cloud-config) file. diff --git a/content/os/installation/running-rancheros/cloud/vmware-esxi/_index.md b/content/os/installation/running-rancheros/cloud/vmware-esxi/_index.md new file mode 100644 index 00000000000..fde35588de8 --- /dev/null +++ b/content/os/installation/running-rancheros/cloud/vmware-esxi/_index.md @@ -0,0 +1,33 @@ +--- +tag: ["rancheros", "os", "vmware", "esxi"] +category: "os" +layout: list-docs +title: VMware ESXi +weight: 108 +--- + +## VMware ESXi +--- + +As of v1.1.0, RancherOS automatically detects that it is running on VMware ESXi, and automatically adds the `open-vm-tools` service to be downloaded and started, and uses `guestinfo` keys to set the cloud-init data. + +### VMware guestinfo + +| VARIABLE | TYPE | +|---|---| +| `hostname` | hostname | +| `interface..name` | string | +| `interface..mac` | MAC address (is used to match the ethernet device's MAC address, not to set it) | +| `interface..dhcp` | {"yes", "no"} | +| `interface..role` | {"public", "private"} | +| `interface..ip..address` | CIDR IP address | +| `interface..route..gateway` | IP address | +| `interface..route..destination` | CIDR IP address (not available yet) | +| `dns.server.` | IP address | +| `dns.domain.` | DNS search domain | +| `cloud-init.config.data` | string | +| `cloud-init.data.encoding` | {"", "base64", "gzip+base64"} | +| `cloud-init.config.url` | URL | + + +> **Note:** "n", "m", "l", "x" and "y" are 0-indexed, incrementing integers. The identifier for an interface (``) is used in the generation of the default interface name in the form `eth`. diff --git a/content/os/installation/running-rancheros/server/install-to-disk/_index.md b/content/os/installation/running-rancheros/server/install-to-disk/_index.md new file mode 100644 index 00000000000..d1befe39415 --- /dev/null +++ b/content/os/installation/running-rancheros/server/install-to-disk/_index.md @@ -0,0 +1,109 @@ +--- +tag: ["rancheros", "os", "install"] +category: "os" +layout: list-docs +title: Installing to Disk +weight: 111 +--- + +## 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]({{page.osbaseurl}}/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]({{page.osbaseurl}}/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... +``` + +
+ +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]: +``` + +For the `cloud-config.yml` file, you can also specify a remote URL, but you need to make sure you can get it: + +``` +$ sudo ros install -c https://link/to/cloud-config.yml +``` + +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]({{page.osbaseurl}}/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 particularly 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@ +``` + +### 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 +INFO[0000] No install type specified...defaulting to generic +Installing from +Continue [y/N]: +``` diff --git a/content/os/installation/running-rancheros/server/pxe/_index.md b/content/os/installation/running-rancheros/server/pxe/_index.md new file mode 100644 index 00000000000..28a204b50b4 --- /dev/null +++ b/content/os/installation/running-rancheros/server/pxe/_index.md @@ -0,0 +1,75 @@ +--- +tag: ["rancheros", "os", "pxe", "ipxe"] +category: "os" +layout: list-docs +title: iPXE +weight: 112 +--- + +## 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 +``` + +### Hiding sensitive kernel commandline parameters + +From RancherOS v0.9.0, secrets can be put on the `kernel` parameters line afer a `--` double dash, and they will be not be shown in any `/proc/cmdline`. These parameters +will be passed to the RancherOS init process and stored in the `root` accessible `/var/lib/rancher/conf/cloud-init.d/init.yml` file, and are available to the root user from the `ros config` commands. + +For example, the `kernel` line above could be written as: + +``` +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] +``` + +The hidden part of the command line can be accessed with either `sudo ros config get rancher.environment.EXTRA_CMDLINE`, or by using a service file's environment array. + +An example service.yml file: + +``` +test: + image: alpine + command: echo "tell me a secret ${EXTRA_CMDLINE}" + labels: + io.rancher.os.scope: system + environment: + - EXTRA_CMDLINE +``` + +When this service is run, the `EXTRA_CMDLINE` will be set. + + +### cloud-init Datasources + +Valid cloud-init datasources for RancherOS. + +| type | default | | +|---|---|--| +| ec2 | ec2's DefaultAddress | | +| file | path | | +| cmdline | /media/config-2 | | +| configdrive | | | +| digitalocean | DefaultAddress | | +| ec2 | DefaultAddress | | +| file | path | | +| gce | | | +| packet | DefaultAddress | | +| url | url | | +| vmware** | | set `guestinfo` cloud-init or interface data as per [VMware ESXi]({{page.osbaseurl}}/cloud/vmware-esxi) | +| * | This will add ["configdrive", "vmware", "ec2", "digitalocean", "packet", "gce"] into the list of datasources to try | | + +** vmware was added as of v1.1. + +### Cloud-Config + +When booting via iPXE, RancherOS can be configured using a [cloud-config file]({{page.osbaseurl}}/configuration/#cloud-config). diff --git a/content/os/installation/running-rancheros/server/raspberry-pi/_index.md b/content/os/installation/running-rancheros/server/raspberry-pi/_index.md new file mode 100644 index 00000000000..96231cdb41d --- /dev/null +++ b/content/os/installation/running-rancheros/server/raspberry-pi/_index.md @@ -0,0 +1,39 @@ +--- +tag: ["rancheros", "os", "raspberry pi"] +category: "os" +layout: list-docs +title: Raspberry Pi +weight: 113 +--- + +## 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]({{page.osbaseurl}}/configuration/#cloud-config). You will need to boot up, change the configuration and then reboot to apply those changes. + +Currently, only Raspberry Pi 3 is tested and known to work. + +> **Note:** It is not necessary to run `ros install` after installing RancherOS to an SD card. + +### 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 diff --git a/content/os/installation/running-rancheros/workstation/boot-from-iso/_index.md b/content/os/installation/running-rancheros/workstation/boot-from-iso/_index.md new file mode 100644 index 00000000000..0b70a979887 --- /dev/null +++ b/content/os/installation/running-rancheros/workstation/boot-from-iso/_index.md @@ -0,0 +1,34 @@ +--- +tag: ["rancheros", "os", "iso"] +category: "os" +layout: list-docs +title: Booting from ISO +weight: 102 +--- + +## 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]({{page.osbaseurl}}/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]({{page.osbaseurl}}/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. diff --git a/content/os/installation/running-rancheros/workstation/docker-machine/_index.md b/content/os/installation/running-rancheros/workstation/docker-machine/_index.md new file mode 100644 index 00000000000..d01c9368061 --- /dev/null +++ b/content/os/installation/running-rancheros/workstation/docker-machine/_index.md @@ -0,0 +1,86 @@ +--- +tag: ["rancheros", "os", "docker machine"] +category: "os" +layout: list-docs +title: Using Docker Machine +weight: 101 +--- + +## 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 +``` + +
+ +> **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 +``` + +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 +``` + +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 +``` + +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]({{page.osbaseurl}}/system-services/adding-system-services/), [customizing the configuration]({{page.osbaseurl}}/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 ) +``` + +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 +``` + +Once you obtain the IP address, paste it in a browser and a _Welcome Page_ for nginx will be displayed. diff --git a/content/os/installation/storage/additional-mounts/_index.md b/content/os/installation/storage/additional-mounts/_index.md new file mode 100644 index 00000000000..514857b2096 --- /dev/null +++ b/content/os/installation/storage/additional-mounts/_index.md @@ -0,0 +1,46 @@ +--- +tag: ["rancheros", "os", "mounts"] +category: "os" +layout: list-docs +title: Additional Mounts +weight: 161 +--- + +## Additional Mounts +--- + +Additional mounts can be specified as part of your [cloud-config]({{page.osbaseurl}}/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", ""] +``` + +**Important**: Be aware, the 4th parameter is mandatory and cannot be ommited (server crashes). It also yet cannot be `defaults` + +As you will use the `ros` cli most probably, it would look like this: + +``` +ros config set mounts '[["/dev/vdb","/mnt/s","ext4",""]]' +``` + +**hint**: You need to pre-format the disks, rancher-os will not do this for you. The mount will not work (silently) until you formatted the disk, e.g. using: + +``` +mkfs.ext4 /dev/vdb +``` + +
+ +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). + +With rancher 1.1.1+ you do no longer need to create the mount-point folder, it will be created automatically. + +### Shared Mounts + +By default, `/media` and `/mnt` are mounted as shared in the console container. This means that mounts within these directories will propagate 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. diff --git a/content/os/installation/storage/state-partition/_index.md b/content/os/installation/storage/state-partition/_index.md new file mode 100644 index 00000000000..c8fa0f1947e --- /dev/null +++ b/content/os/installation/storage/state-partition/_index.md @@ -0,0 +1,39 @@ +--- +tag: ["rancheros", "os"] +category: "os" +layout: list-docs +title: Persistent State Partition +weight: 160 +--- + +## 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 + +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` (_not_ what is set in `fstype`) if the device specified in `autoformat`: + +* Contains a boot2docker magic string +* Starts with 1 megabyte of zeros and `rancher.state.formatzero` is true + + +```yaml +#cloud-config +rancher: + state: + autoformat: + - /dev/sda + - /dev/vda +``` diff --git a/content/os/installation/storage/using-zfs/_index.md b/content/os/installation/storage/using-zfs/_index.md new file mode 100644 index 00000000000..4bc486c254b --- /dev/null +++ b/content/os/installation/storage/using-zfs/_index.md @@ -0,0 +1,127 @@ +--- +tag: ["rancheros", "os", "zfs"] +category: "os" +layout: list-docs +title: Using ZFS +weight: 162 +--- + +## Using ZFS +--- + +#### Installing the ZFS service + +The `zfs` service will install the kernel-headers for your kernel (if you build your own kernel, you'll need to replicate this service), and then download the [ZFS on Linux]() source, and build and install it. Then it will build a `zfs-tools` image that will be used to give you access to the zfs tools. + +The only restriction is that you must mount your zpool into `/mnt`, as this is the only shared mount directory that will be accessible throughout the system-docker managed containers (including the console). + + +``` +$ sudo ros service enable zfs +$ sudo ros service up zfs +# you can follow the progress of the build by running the following command in another ssh session: +$ sudo ros service logs --follow zfs +# wait until the build is finished. +$ lsmod | grep zfs +``` + +> *Note:* if you switch consoles, you may need to re-run `ros up zfs`. + +#### Creating ZFS pools + +After it's installed, it should be ready to use. Make a zpool named `zpool1` using a device that you haven't yet partitioned (you can use `sudo fdisk -l` to list all the disks and their partitions). + +> *Note:* You need to mount the zpool in `/mnt` to make it available to your host and in containers. + + +``` +$ sudo zpool list +$ sudo zpool create zpool1 -m /mnt/zpool1 /dev/ +$ sudo zpool list +$ sudo zfs list +$ sudo cp /etc/* /mnt/zpool1 +$ docker run --rm -it -v /mnt/zpool1/:/data alpine ls -la /data +``` + +
+ +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. + +#### Using the ZFS debugger utility + +The `zdb` command may be used to display information about ZFS pools useful to diagnose failures and gather statistics. By default the utility tries to load pool configurations from `/etc/zfs/zpool.cache`. Since the RancherOS ZFS service does not make use of the ZFS cache file and instead detects pools by inspecting devices, the `zdb` utility has to be invoked with the `-e` flag. + +E.g. to show the configuration for the pool `zpool1` you may run the following command: + +> $ sudo zdb -e -C zpool1 + +## 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 'zfs' +$ sudo ros config set rancher.docker.graph /mnt/zpool1/docker +# Now that you've changed the 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: 0 + Running: 0 + Paused: 0 + Stopped: 0 +Images: 0 +Server Version: 1.12.6 +Storage Driver: zfs + Zpool: error while getting pool information strconv.ParseUint: parsing "": invalid syntax + Zpool Health: not available + Parent Dataset: zpool1/docker + Space Used By Parent: 19456 + Space Available: 8256371200 + Parent Quota: no + Compression: off +Logging Driver: json-file +Cgroup Driver: cgroupfs +Plugins: + Volume: local + Network: host bridge null overlay +Swarm: inactive +Runtimes: runc +Default Runtime: runc +Security Options: seccomp +Kernel Version: 4.9.6-rancher +Operating System: RancherOS v0.8.0-rc8 +OSType: linux +Architecture: x86_64 +CPUs: 1 +Total Memory: 1.953 GiB +Name: ip-172-31-24-201.us-west-1.compute.internal +ID: IEE7:YTUL:Y3F5:L6LF:5WI7:LECX:YDB5:LGWZ:QRPN:4KDI:LD66:KYTC +Docker Root Dir: /mnt/zpool1/docker +Debug Mode (client): false +Debug Mode (server): false +Registry: https://index.docker.io/v1/ +Insecure Registries: + 127.0.0.0/8 + +``` diff --git a/content/os/installation/system-services/adding-system-services/_index.md b/content/os/installation/system-services/adding-system-services/_index.md new file mode 100644 index 00000000000..a1c672c6252 --- /dev/null +++ b/content/os/installation/system-services/adding-system-services/_index.md @@ -0,0 +1,55 @@ +--- +tag: ["rancheros", "os", "system services"] +category: "os" +layout: list-docs +title: System Services +weight: 140 +--- + +## 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 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 +``` + +
+If you want to remove a system service from the list of service, just delete the service. + +``` +$ sudo ros service delete +``` diff --git a/content/os/installation/system-services/custom-system-services/_index.md b/content/os/installation/system-services/custom-system-services/_index.md new file mode 100644 index 00000000000..e3c0c259bb6 --- /dev/null +++ b/content/os/installation/system-services/custom-system-services/_index.md @@ -0,0 +1,214 @@ +--- +tag: ["rancheros", "os", "system services"] +category: "os" +layout: list-docs +title: Custom System Services +weight: 141 +--- + +## 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]({{page.osbaseurl}}/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 Services using local files + +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 +``` + +
+ +After the custom system service is enabled, you can start the service using `sudo ros service up `. The `` will be the names of the services inside the `docker-compose.yml`. + +``` +$ sudo ros service up nginxapp +# If you have more than 1 service in your docker-compose.yml, add all service names to the command +$ sudo ros service up service1 service2 service3 +``` + +### Launching Services from a web repository + +The https://github.com/rancher/os-services repository is used for the built-in services, but you can create your own, and configure RancherOS to use it in addition (or to replace) it. + +The config settings to set the url in which `ros` should look for an `index.yml` file is: `rancher.repositories..url`. The `core` repository url is set when a release is made, and any other `` url you add will be listed together when running `ros console list`, `ros service list` or `ros engine list` + +For example, in RancherOS v0.7.0, the `core` repository is set to `https://raw.githubusercontent.com/rancher/os-services/v0.7.0`. + +### Service development and testing + +If you're building your own services in a branch on GitHub, you can push to it, and then load your service from there. + +For example, when developing the zfs service: + +``` +rancher@zfs:~$ sudo ros config set rancher.repositories.zfs.url https://raw.githubusercontent.com/SvenDowideit/os-services/zfs-service +rancher@zfs:~$ sudo ros service list +disabled amazon-ecs-agent +disabled kernel-extras +enabled kernel-headers +disabled kernel-headers-system-docker +disabled open-vm-tools +disabled amazon-ecs-agent +disabled kernel-extras +disabled kernel-headers +disabled kernel-headers-system-docker +disabled open-vm-tools +disabled zfs +[rancher@zfs ~]$ sudo ros service enable zfs +Pulling zfs (zombie/zfs)... +latest: Pulling from zombie/zfs +b3e1c725a85f: Pull complete +4daad8bdde31: Pull complete +63fe8c0068a8: Pull complete +4a70713c436f: Pull complete +bd842a2105a8: Pull complete +d1a8c0826fbb: Pull complete +5f1c5ffdf34c: Pull complete +66c2263f2388: Pull complete +Digest: sha256:eab7b8c21fbefb55f7ee311dd236acee215cb6a5d22942844178b8c6d4e02cd9 +Status: Downloaded newer image for zombie/zfs:latest +[rancher@zfs ~]$ sudo ros service up zfs +WARN[0000] The KERNEL_VERSION variable is not set. Substituting a blank string. +INFO[0000] Project [os]: Starting project +INFO[0000] [0/21] [zfs]: Starting +INFO[0000] [1/21] [zfs]: Started +INFO[0000] Project [os]: Project started + +``` + +Beware that there is an overly aggressive caching of yml files - so when you push a new yml file to your repo, you need to +delete the files in `/var/lib/rancher/cache`. + +The image that you specify in the service yml file needs to be pullable - either from a private registry, or on the Docker Hub. + +### Service cron + +_Available as of v1.1_ + +RancherOS has a system cron service based on [Container Crontab](https://github.com/rancher/container-crontab). This can be used to start, restart or stop system containers. + +To use this on your service, add a `cron.schedule` label to your service's description: + +``` +my-service: + image: namespace/my-service:v1.0.0 + command: my-command + labels: + io.rancher.os.scope: "system" + cron.schedule: "0 * * * * ?" +``` + +For a cron service that can be used with user Docker containers, see the `crontab` system service. + +### Service log rotation + +RancherOS provides a built in `logrotate` container that makes use of logrotate(8) to rotate system logs. This is called on an hourly basis by the `system-cron` container. + +If you would like to make use of system log rotation for your system service, do the following. + +Add `system-volumes` to your service description's `volumes_from` section. You could also use a volume group containing `system-volumes` e.g. `all-volumes`. + +``` +my-service: + image: namespace/my-service:v1.0.0 + command: my-command + labels: + io.rancher.os.scope: "system" + volumes_from: + - system-volumes +``` + +Next, add an entry point script to your image and copy your logrotate configs to `/etc/logrotate.d/` on startup. + +Example Dockerfile: +``` +FROM alpine:latest +COPY logrotate-myservice.conf entrypoint.sh / +ENTRYPOINT ["/entrypoint.sh"] +``` + +Example entrypoint.sh (Ensure that this script has the execute bit set). +``` +#!/bin/sh + +cp logrotate-myservice.conf /etc/logrotate.d/myservice + +exec "$@" +``` + +Your service's log rotation config will now be included when the system logrotate runs. You can view logrotate output with `system-docker logs logrotate`. + +### Creating your own Console + +Once you have your own Services repository, you can add a new service to its index.yml, and then add a `.yml` file to the directory starting with the first letter. + +To create your own console images, you need to: + +1 install some basic tools, including an ssh daemon, sudo, and kernel module tools +2 create `rancher` and `docker` users and groups with UID and GID's of `1100` and `1101` respectively +3 add both users to the `docker` and `sudo` groups +4 add both groups into the `/etc/sudoers` file to allow password-less sudo +5 configure sshd to accept logins from users in the `docker` group, and deny `root`. +6 set `ENTRYPOINT ["/usr/bin/ros", "entrypoint"]` + +the `ros` binary, and other host specific configuration files will be bind mounted into the running console container when its launched. + +For examples of existing images, see https://github.com/rancher/os-images. + +## 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. + + +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 User Docker. + +```yaml +labels: + - io.rancher.os.scope=system +``` + + +### 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 +``` diff --git a/content/os/installation/system-services/environment/_index.md b/content/os/installation/system-services/environment/_index.md new file mode 100644 index 00000000000..7c9cddf8e41 --- /dev/null +++ b/content/os/installation/system-services/environment/_index.md @@ -0,0 +1,48 @@ +--- +tag: ["rancheros", "os", "system services", "environment"] +category: "os" +layout: list-docs +title: Environment +weight: 143 +--- + +## 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_* +``` + +_Available as of v1.2_ + +There is also a way to extend PATH environment variable, `PATH` or `path` can be set, and multiple values can be comma-separated. Note that need to reboot before taking effect. + +```yaml +rancher: + environment: + path: /opt/bin,/home/rancher/bin +``` diff --git a/content/os/installation/system-services/system-docker-volumes/_index.md b/content/os/installation/system-services/system-docker-volumes/_index.md new file mode 100644 index 00000000000..0a3ec457955 --- /dev/null +++ b/content/os/installation/system-services/system-docker-volumes/_index.md @@ -0,0 +1,90 @@ +--- +tag: ["rancheros", "os", "system services"] +category: "os" +layout: list-docs +title: System Docker Volumes +weight: 142 +--- + +## 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 +/var/lib/kubelet - Added as of v1.2 +``` + +_Available as of v1.2_ + +If you want to change user-volumes, for example, add `/etc/kubernetes` directory: + +``` +$ sudo ros config set rancher.services.user-volumes.volumes [/home:/home,/opt:/opt,/var/lib/kubelet:/var/lib/kubelet,/etc/kubernetes:/etc/kubernetes] +$ sudo reboot +``` + +Please note that after the restart, the new persistence directory can take effect. + +### 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/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. diff --git a/content/os/one/_index.md b/content/os/one/_index.md deleted file mode 100644 index 0c0e0671681..00000000000 --- a/content/os/one/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: One - weight: 1 ---- - - -hello diff --git a/content/os/one/a-placeholder.md b/content/os/one/a-placeholder.md deleted file mode 100644 index 64245b28a29..00000000000 --- a/content/os/one/a-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder a ---- - -# one tasks placeholder md diff --git a/content/os/one/b-placeholder.md b/content/os/one/b-placeholder.md deleted file mode 100644 index 4c40643c37e..00000000000 --- a/content/os/one/b-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder b ---- - -# two tasks placeholder md diff --git a/content/os/one/c-placeholder.md b/content/os/one/c-placeholder.md deleted file mode 100644 index 2b3baed6fac..00000000000 --- a/content/os/one/c-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder c ---- - -# three tasks placeholder md diff --git a/content/os/one/one-nested/_index.md b/content/os/one/one-nested/_index.md deleted file mode 100644 index 11d50bc7db3..00000000000 --- a/content/os/one/one-nested/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: one nested - weight: 2 ---- - - -hello diff --git a/content/os/one/one-nested/two-placeholder.md b/content/os/one/one-nested/two-placeholder.md deleted file mode 100644 index e08de18f3e0..00000000000 --- a/content/os/one/one-nested/two-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: one nested a ---- - -# two tasks placeholder md diff --git a/content/os/one/one-placeholder.md b/content/os/one/one-placeholder.md deleted file mode 100644 index 64245b28a29..00000000000 --- a/content/os/one/one-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder a ---- - -# one tasks placeholder md diff --git a/content/os/one/three-placeholder.md b/content/os/one/three-placeholder.md deleted file mode 100644 index 2b3baed6fac..00000000000 --- a/content/os/one/three-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder c ---- - -# three tasks placeholder md diff --git a/content/os/one/two-placeholder.md b/content/os/one/two-placeholder.md deleted file mode 100644 index 4c40643c37e..00000000000 --- a/content/os/one/two-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder b ---- - -# two tasks placeholder md diff --git a/content/os/quick-start-guide/_index.md b/content/os/quick-start-guide/_index.md new file mode 100644 index 00000000000..bae784dfcab --- /dev/null +++ b/content/os/quick-start-guide/_index.md @@ -0,0 +1,135 @@ +--- +tag: ["rancheros", "os", "quick-start-guide"] +category: "os" +layout: list-docs +title: Quick Start Guide +weight: 2 +--- + + +## Quick Start Guide +--- + +If you have a specific RanchersOS machine requirements, please check out our [guides on running RancherOS]({{page.osbaseurl}}/running-rancheros/). With the rest of this guide, we'll start up a RancherOS using [Docker machine]({{page.osbaseurl}}/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 +``` + +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 +``` + +### 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://`. + +![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.network.dns.nameservers +- 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]({{page.osbaseurl}}/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. diff --git a/content/os/three/_index.md b/content/os/three/_index.md deleted file mode 100644 index e0467a8c5e8..00000000000 --- a/content/os/three/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: Three - weight: 3 ---- - - -hello diff --git a/content/os/three/three-placeholder.md b/content/os/three/three-placeholder.md deleted file mode 100644 index da4e9c89bce..00000000000 --- a/content/os/three/three-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: placeholder ---- - -# three tasks placeholder md diff --git a/content/os/two/_index.md b/content/os/two/_index.md deleted file mode 100644 index d24a458db7d..00000000000 --- a/content/os/two/_index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "category" - layout: list-docs - title: Two - weight: 2 ---- - - -hello diff --git a/content/os/two/two-placeholder.md b/content/os/two/two-placeholder.md deleted file mode 100644 index 11772ff4e88..00000000000 --- a/content/os/two/two-placeholder.md +++ /dev/null @@ -1,8 +0,0 @@ ---- - tag: ["tag1", "tag2", "tag3"] - category: "categories" - layout: single-docs - title: two placeholder ---- - -# two tasks placeholder md diff --git a/content/os/upgrading/_index.md b/content/os/upgrading/_index.md new file mode 100644 index 00000000000..b38fc512be9 --- /dev/null +++ b/content/os/upgrading/_index.md @@ -0,0 +1,143 @@ +--- +tag: ["rancheros", "os", "upgrade"] +category: "os" +layout: list-docs +title: Upgrading RancherOS +weight: 200 +--- + +## 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 Syslinux bootloader. + +To see all of our releases, please visit our [releases page](https://github.com/rancher/os/releases) in GitHub. + +> **Note:** If you are using [`docker-machine`]({{page.osbaseurl}}/running-rancheros/workstation/docker-machine/) then you will not be able to upgrade your RancherOS version. You need to delete and re-create the machine. + + +### 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]({{page.osbaseurl}}/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 +``` + +
+ +> **Note:** If you are using a [persistent console]({{page.osbaseurl}}/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 +```