# rkt Commands

Work in progress. Please contribute if you see an area that needs more detail.

## Downloading Images (ACIs)

[aci-images]: https://github.com/appc/spec/blob/master/spec/aci.md#app-container-image
[appc-discovery]: https://github.com/appc/spec/blob/master/spec/discovery.md#app-container-image-discovery

rkt runs applications packaged as [Application Container Images (ACI)][aci-images] an open-source specification. ACIs consist of the root filesystem of the application container, a manifest and an optional signature.

ACIs are named with a URL-like structure. This naming scheme allows for a decentralized discovery of ACIs, related signatures and public keys. rkt uses these hints to execute [meta discovery][appc-discovery].

### rkt trust

Before executing a remotely fetched ACI, rkt will verify it based on attached signatures generated by the ACI creator.

Before this can happen, rkt needs to know which creators you trust, and therefore are trusted to run images on your machine. The identity of each ACI creator is established with a public key, which is placed in rkt's key store on disk.

When adding a trusted key, a prefix can scope the level of established trust to a subset of images. A few examples:

```
$rkt trust --prefix storage.coreos.com
```

```
$rkt trust --prefix coreos.com/etcd
```

To trust a key for an entire root domain, you must use the `--root` flag.

```
$rkt trust --root coreos.com
```

#### Trust a Key Using Meta Discovery

The easiest way to trust a key is through meta discovery. rkt will find and download a public key that the creator has published on their website. This process is detailed in the [Application Container specification][appc-discovery]. The TL;DR is rkt will find a meta tag that looks like:

```
<meta name="ac-discovery-pubkeys" content="coreos.com/etcd https://coreos.com/dist/pubkeys/aci-pubkeys.gpg">
```

And use it to download the public key and present it to you for approval:

```
$ rkt trust --prefix coreos.com/etcd
Prefix: "coreos.com/etcd"
Key: "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg"
GPG key fingerprint is: 8B86 DE38 890D DB72 9186  7B02 5210 BD88 8818 2190
  CoreOS ACI Builder <release@coreos.com>
Are you sure you want to trust this key (yes/no)? yes
Trusting "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" for prefix "coreos.com/etcd".
Added key for prefix "coreos.com/etcd" at "/etc/rkt/trustedkeys/prefix.d/coreos.com/etcd/8b86de38890ddb7291867b025210bd8888182190"
```

If rkt can't find a key using meta discovery, an error will be printed:

```
$ rkt trust --prefix coreos.com                     
Error determining key location: --prefix meta discovery error: found no ACI meta tags
```

#### Trust a Key From Specific Location

If you know where a public key is located, you can request it directly from disk or via HTTPS:

```
$ sudo ./rkt trust --prefix coreos.com/etcd https://coreos.com/dist/pubkeys/aci-pubkeys.gpg
Prefix: "coreos.com/etcd"
Key: "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg"
GPG key fingerprint is: 8B86 DE38 890D DB72 9186  7B02 5210 BD88 8818 2190
  CoreOS ACI Builder <release@coreos.com>
Are you sure you want to trust this key (yes/no)? yes
Trusting "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" for prefix "coreos.com/etcd".
Added key for prefix "coreos.com/etcd" at "/etc/rkt/trustedkeys/prefix.d/coreos.com/etcd/8b86de38890ddb7291867b025210bd8888182190"
```

#### Pre-Populating Trusted Keys on Disk

Trusted public keys can be pre-populated by placing them in the appropriate location on disk for the desired prefix.

_Depends on https://github.com/coreos/rkt/issues/500_
```
$ ls -l /etc/rkt/trustedkeys/
[insert example of root key vs prefixed key]
```

### rkt fetch

rkt uses HTTPS to locate and download remote ACIs and their attached signatures. If the ACI exists locally, it won't be re-downloaded.

#### Fetch with Meta Discovery

The easiest way to fetch an ACI is through meta discovery. rkt will find and download the ACI and signature from a location that the creator has published on their website. This process is detailed in the [Application Container specification][appc-discovery].

If you have previously trusted the image creator, it will be downloaded and verified: 

```
$ rkt fetch coreos.com/etcd:v2.0.0
rkt: searching for app image coreos.com/etcd:v2.0.0
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
Downloading aci: [=======================================      ] 3.25 MB/3.7 MB
Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.sig
rkt: signature verified: 
  CoreOS ACI Builder <release@coreos.com>
sha512-fa1cb92dc276b0f9bedf87981e61ecde
```

If you haven't trusted the creator, it will be downloaded but not verified:

```
$ sudo ./rkt fetch coreos.com/etcd:v2.0.0
rkt: searching for app image coreos.com/etcd:v2.0.0
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
Downloading aci: [=======================================      ] 3.25 MB/3.7 MB
Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.sig
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
sha512-fa1cb92dc276b0f9bedf87981e61ecde
```

#### Fetch from Specific Location

If you already know where an image is stored, you can fetch it directly:

```
$ rkt fetch https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
Downloading aci: [=======================================      ] 3.25 MB/3.7 MB
Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.sig
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
sha512-fa1cb92dc276b0f9bedf87981e61ecde
```

#### Fetch from a Docker registry

If you want to run an existing Docker image, you can fetch from a Docker registry. rkt will download and convert the image to ACI.

```
$ rkt -insecure-skip-verify fetch docker://busybox
rkt: fetching image from docker://busybox
rkt: warning: signature verification has been disabled
Downloading layer: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Downloading layer: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Downloading layer: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
Downloading layer: 511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158
sha512-c4010045aec65aefa74770ef2bb648d9
```

Docker images do not support signature verification.

## Running Pods

rkt can run ACIs based on name, hash, local file on disk or URL. If an ACI hasn't been cached on disk, rkt will attempt to find and download it.

### rkt run

#### Image Addressing

Images can be run by either their name, their hash, an explicit transport address, or a Docker registry URL.

```
# Run by name
$ sudo rkt run coreos.com/etcd:v2.0.0
```

```
# Run by hash
$ sudo rkt run sha512-fa1cb92dc276b0f9bedf87981e61ecde
```

```
# Run by ACI address
$ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
```

```
# Run by Docker registry
$ sudo rkt run docker://quay.io/coreos/etcd:v2.0.0
```

#### Passing Arguments

To pass additional arguments to images use the pattern of `image1 -- [image1 flags] --- image2 -- [image2 flags]`.
For example:

```
$ sudo rkt run example.com/worker -- --loglevel verbose --- example.com/syncer -- --interval 30s
```

#### Influencing Environment Variables

To inherit all environment variables from the parent use the `--inherit-env` flag.

To explicitly set individual environment variables use the `--set-env` flag.

The precedence is as follows with the last item replacing previous environment entries:

- Parent environment
- App image environment
- Explicitly set environment

```
$ export EXAMPLE_ENV=hello
$ export EXAMPLE_OVERRIDE=under
$ sudo rkt run --inherit-env --set-env FOO=bar --set-env EXAMPLE_OVERRIDE=over example.com/env-printer
EXAMPLE_ENV=hello
FOO=bar
EXAMPLE_OVERRIDE=over
```

_TODO: Exit codes_

#### Disable Signature Verification

If desired, `-insecure-skip-verify` can be used to disable this security check:

```
$ sudo rkt -insecure-skip-verify run coreos.com/etcd:v2.0.0
rkt: searching for app image coreos.com/etcd:v2.0.0
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
rkt: warning: signature verification has been disabled
...
```

#### Mount Volumes into a Pod

Volumes are defined in each ACI and are referenced by name. Volumes can be exposed from the host into the pod (`host`) or initialized as empty storage to be accessed locally within the pod (`empty` pending [rkt #378][rkt #378]). Each volume can be selectively mounted into each application at differing mount points or not mounted into specific apps at all.

[rkt #378]: https://github.com/coreos/rkt/issues/378


##### Mounting Host Volumes 

For `host` volumes, the `--volume` flag allows you to specify each mount, its type and the location on the host. The volume is then mounted into each app running to the pod based on information defined in the ACI manifest.

For example, let's say we want to read data from the host directory `/opt/tenant1/work` to power a MapReduce-style worker. We'll call this app `example.com/reduce-worker`.

We also want this data to be available to a backup application that runs alongside the worker (in the same pod). We'll call this app 'example.com/worker-backup`. The backup application only needs read-only access to the data.

Below we show the abbreviated manifests for the respective applications (recall that the manifest is bundled into the application's ACI):

```
{
    "acKind": "ImageManifest",
    "name": "example.com/reduce-worker",
    ...
    "app": {
        ...
        "mountPoints": [
            {
                "name": "work",
                "path": "/var/lib/work",
                "readOnly": false
            }
        ],
    ...
}
```

```
{
    "acKind": "ImageManifest",
    "name": "example.com/worker-backup",
    ...
    "app": {
        ...
        "mountPoints": [
            {
                "name": "work",
                "path": "/backup",
                "readOnly": true
            }
        ],
    ...
}
```

In this case, both apps reference a volume they call "work", and expect it to be made available at `/var/lib/work` and `/backup` within their respective root filesystems. 

Since they reference the volume using an abstract name rather than a specific source path, the same image can be used on a variety of different hosts without being coupled to the host's filesystem layout.

To tie it all together, we use the `rkt run` command-line to provide them with a volume by this name. Here's what it looks like:

```
sudo ./rkt run --volume work,kind=host,source=/opt/tenant1/work \
  example.com/reduce-worker \
  example.com/worker-backup
```

Now when the pod is running, the two apps will see the host's `/opt/tenant1/work` directory made available at their expected locations.

#### Customize Networking

The default networking configuration for rkt is "host networking". This means that the apps within the pod will share the network stack and the interfaces with the host machine. Since the metadata service uses the pod IP for identity, rkt will not register the pod with the metadata service in this mode.

##### Private Networking

Another common configuration, "private networking", means the pod will be executed with its own network stack. This is similar to how other container tools work. The [metadata service](metadata-service.md) (launched via `rkt metadata-service`) must be running to use private networking.

By default, rkt private networking will create a loopback device and a veth device. The veth pair creates a point-to-point link between the pod and the host. rkt will allocate an IPv4 /31 (2 IP addresses) out of 172.16.28.0/24 and assign one IP to each end of the veth pair. It will additionally set a route for metadata service (169.254.169.255/32) and default route in the pod namespace. Finally, it will enable IP masquerading on the host to NAT the egress traffic.

```
sudo ./rkt run --private-net coreos.com/etcd:v2.0.0
```

##### Other Networking Examples

Additional networking modes and more examples can be found in the [networking documentation](networking.md)

#### Use a Custom Stage 1

Work in progress. Please contribute!

#### Run a Pod in the Background

Work in progress. Please contribute!

### Logging

By default, rkt will send logs directly to stdout/stderr, allowing them to be caputered by the invoking process.
On host systems running systemd, rkt will attempt to integrate with journald on the host.
In this case, the logs can be accessed directly via journalctl.

NOTE: Journald integration requires systemd version v219 or v220 in stage1.

#### Accessing logs via journalctl

To get the logs you need to get pod's machine name. You can use machinectl

```
$ machinectl
MACHINE                                  CLASS     SERVICE
rkt-f241c969-1710-445a-8129-d3a7ffdd9a60 container nspawn

1 machines listed.
```

or `rkt list --full`

```
# rkt list --full
UUID                                    ACI     STATE   NETWORKS
f241c969-1710-445a-8129-d3a7ffdd9a60    busybox running
```

Pod's machine name will be the pod's UUID with a `rkt-` prefix.

Then you can use systemd's journalctl with `_HOSTNAME` set to the machine name:

```
$ journalctl -m _HOSTNAME=rkt-f241c969-1710-445a-8129-d3a7ffdd9a60

[...]
```

rkt doesn't integrate with `journalctl -M` yet (see https://github.com/coreos/rkt/issues/947).

### rkt status

Work in progress. Please contribute!

### rkt enter

Work in progress. Please contribute!

## Metadata Service

Work in progress. Please contribute!

### rkt metadata-service

Work in progress. Please contribute!

## Other Commands

### rkt gc

rkt has a built-in garbage collection command that is designed to be run periodically from a timer or cron job. Stopped pods are moved to the garbage and cleaned up during a subsequent garbage collection pass. Each `gc` pass removes any pods remaining in the garbage past the grace period. [Read more about the pod lifecycle][gc-docs].

[gc-docs]: devel/pod-lifecycle.md#garbage-collection

```
$ rkt gc --grace-period=30m0s
Moving pod "21b1cb32-c156-4d26-82ae-eda1ab60f595" to garbage
Moving pod "5dd42e9c-7413-49a9-9113-c2a8327d08ab" to garbage
Moving pod "f07a4070-79a9-4db0-ae65-a090c9c393a3" to garbage
```

On the next pass, the pods are removed:

```
$ rkt gc --grace-period=30m0s
Garbage collecting pod "21b1cb32-c156-4d26-82ae-eda1ab60f595"
Garbage collecting pod "5dd42e9c-7413-49a9-9113-c2a8327d08ab"
Garbage collecting pod "f07a4070-79a9-4db0-ae65-a090c9c393a3"
```