github.com/coreos/rocket@v1.30.1-0.20200224141603-171c416fac02/Documentation/commands.md (about)

     1  # rkt Commands
     2  
     3  Work in progress.
     4  Please contribute if you see an area that needs more detail.
     5  
     6  ## Downloading Images (ACIs)
     7  
     8  rkt runs applications packaged according to the open-source [App Container Image][aci-images] specification.
     9  ACIs consist of the root filesystem of the application container, a manifest, and an optional signature.
    10  
    11  ACIs are named with a URL-like structure.
    12  This naming scheme allows for a decentralized discovery of ACIs, related signatures and public keys.
    13  rkt uses these hints to execute [meta discovery][appc-discovery].
    14  
    15  * [trust](subcommands/trust.md)
    16  * [fetch](subcommands/fetch.md)
    17  
    18  ## Running Pods
    19  
    20  rkt can execute ACIs identified by name, hash, local file path, or URL.
    21  If an ACI hasn't been cached on disk, rkt will attempt to find and download it.
    22  To use rkt's [metadata service][metadata-spec], enable registration with the `--mds-register` flag when [invoking it][rkt-mds].
    23  
    24  * [run](subcommands/run.md)
    25  * [stop](subcommands/stop.md)
    26  * [enter](subcommands/enter.md)
    27  * [prepare](subcommands/prepare.md)
    28  * [run-prepared](subcommands/run-prepared.md)
    29  
    30  ## Pod inspection and management
    31  
    32  rkt provides subcommands to list, get status, and clean its pods.
    33  
    34  * [list](subcommands/list.md)
    35  * [status](subcommands/status.md)
    36  * [export](subcommands/export.md)
    37  * [gc](subcommands/gc.md)
    38  * [rm](subcommands/rm.md)
    39  * [cat-manifest](subcommands/cat-manifest.md)
    40  
    41  ## Interacting with the local image store
    42  
    43  rkt provides subcommands to list, inspect and export images in its local store.
    44  
    45  * [image](subcommands/image.md)
    46  
    47  ## Metadata Service
    48  
    49  The metadata service helps running apps introspect their execution environment and assert their pod identity.
    50  
    51  * [metadata-service](subcommands/metadata-service.md)
    52  
    53  ## API Service
    54  
    55  The API service allows clients to list and inspect pods and images running under rkt.
    56  
    57  * [api-service](subcommands/api-service.md)
    58  
    59  ## Misc
    60  
    61  * [version](subcommands/version.md)
    62  * [config](subcommands/config.md)
    63  
    64  ## Global Options
    65  
    66  In addition to the flags used by individual `rkt` commands, `rkt` has a set of global options that are applicable to all commands.
    67  
    68  | Flag | Default | Options | Description |
    69  | --- | --- | --- | --- |
    70  | `--cpuprofile (hidden flag)` | ''  | A file path | Write CPU profile to the file |
    71  | `--debug` |  `false` | `true` or `false` | Prints out more debug information to `stderr` |
    72  | `--dir` | `/var/lib/rkt` | A directory path | Path to the `rkt` data directory |
    73  | `--insecure-options` |  none | **none**, **http**, **image**, **tls**, **pubkey**, **capabilities**, **paths**, **seccomp**, **all-fetch**, **all-run**, **all** <br/> More information below. | Comma-separated list of security features to disable |
    74  | `--local-config` |  `/etc/rkt` | A directory path | Path to the local configuration directory |
    75  | `--memprofile (hidden flag)` | '' | A file path | Write memory profile to the file |
    76  | `--system-config` |  `/usr/lib/rkt` | A directory path | Path to the system configuration directory |
    77  | `--trust-keys-from-https` |  `false` | `true` or `false` | Automatically trust gpg keys fetched from HTTPS (or HTTP if the insecure `pubkey` option is also specified) |
    78  | `--user-config` | '' | A directory path | Path to the user configuration directory |
    79  
    80  ### `--insecure-options`
    81  
    82  - **none**: All security features are enabled
    83  - **http**: Allow HTTP connections. Be warned that this will send any credentials as clear text, allowing anybody with access to your network to obtain them. It will also perform no validation of the remote server, making it possible for an attacker to impersonate the remote server. This applies specifically to fetching images, signatures, and gpg pubkeys.
    84  - **image**: Disables verifying image signatures. If someone is able to replace the image on the server with a modified one or is in a position to impersonate the server, they will be able to force you to run arbitrary code.
    85  - **tls**: Accept any certificate from the server and any host name in that certificate. This will make it possible for attackers to spoof the remote server and provide malicious images.
    86  - **pubkey**: Allow fetching pubkeys via insecure connections (via HTTP connections or from servers with unverified certificates). This slightly extends the meaning of the `--trust-keys-from-https` flag. This will make it possible for an attacker to spoof the remote server, potentially providing fake keys and allowing them to provide container images that have been tampered with.
    87  - **capabilities**: Gives all [capabilities][capabilities] to apps. This allows an attacker that is able to execute code in the container to trivially escalate to root privileges on the host. 
    88  - **paths**: Disables inaccessible and read-only paths. This makes it easier for an attacker who can gain control over a single container to execute code in the host system, potentially allowing them to escape from the container. This also leaks additional information.
    89  - **seccomp**: Disables [seccomp][seccomp]. This increases the attack surface available to an attacker who can gain control over a single container, potentially making it easier for them to escape from the container.
    90  - **all-fetch**: Disables the following security checks: image, tls, http
    91  - **all-run**: Disables the following security checks: capabilities, paths, seccomp
    92  - **all**: Disables all security checks
    93  
    94  ## Logging
    95  
    96  By default, rkt will send logs directly to stdout/stderr, allowing them to be captured by the invoking process.
    97  On host systems running systemd, rkt will attempt to integrate with journald on the host.
    98  In this case, the logs can be accessed directly via journalctl.
    99  
   100  #### Accessing logs via journalctl
   101  
   102  To read the logs of a running pod, get the pod's machine name from `machinectl`:
   103  
   104  ```
   105  $ machinectl
   106  MACHINE                                  CLASS     SERVICE
   107  rkt-bc3c1451-2e81-45c6-aeb0-807db44e31b4 container rkt
   108  
   109  1 machines listed.
   110  ```
   111  
   112  or `rkt list --full`
   113  
   114  ```
   115  $ rkt list --full
   116  UUID                                  APP    IMAGE NAME                              IMAGE ID             STATE    CREATED                             STARTED                             NETWORKS
   117  bc3c1451-2e81-45c6-aeb0-807db44e31b4  etcd   coreos.com/etcd:v2.3.4                  sha512-7f05a10f6d2c  running  2016-05-18 10:07:35.312 +0200 CEST  2016-05-18 10:07:35.405 +0200 CEST  default:ip4=172.16.28.83
   118                                        redis  registry-1.docker.io/library/redis:3.2  sha512-6eaaf936bc76
   119  ```
   120  
   121  The pod's machine name will be the pod's UUID prefixed with `rkt-`.
   122  Given this machine name, logs can be retrieved by `journalctl`:
   123  
   124  ```
   125  $ journalctl -M rkt-bc3c1451-2e81-45c6-aeb0-807db44e31b4
   126  [...]
   127  ```
   128  
   129  To get logs from one app in the pod:
   130  
   131  ```
   132  $ journalctl -M rkt-bc3c1451-2e81-45c6-aeb0-807db44e31b4 -t etcd
   133  [...]
   134  $ journalctl -M rkt-bc3c1451-2e81-45c6-aeb0-807db44e31b4 -t redis
   135  [...]
   136  ```
   137  
   138  Additionally, logs can be programmatically accessed via the [sd-journal API][sd-journal].
   139  
   140  Currently there are two known main issues with logging in rkt:
   141  * In some rare situations when an application inside the pod is writing to `/dev/stdout` and `/dev/stderr` (i.e. nginx) there is no way to obtain logs.
   142   The app should be modified so it will write to `stdout` or `syslog`. In the case of nginx the following snippet should be added to ```/etc/nginx/nginx.conf```:
   143  
   144  ```
   145  error_log stderr;
   146  
   147  http {
   148      access_log syslog:server=unix:/dev/log main;
   149      [...]
   150  }
   151  ```
   152  
   153  * Some applications, like etcd 3.0, write directly to journald. Such log entries will not be written to stdout or stderr.
   154   These logs can be retrieved by passing the machine ID to journalctl:
   155  
   156  
   157  ```
   158  $ journalctl -M rkt-bc3c1451-2e81-45c6-aeb0-807db44e31b4
   159  ```
   160  
   161  For the specific etcd case, since release 3.1.0-rc.1 it is possible to force emitting logs to stdout via a `--log-output=stdout` command-line option.
   162  
   163  ##### Stopped pod
   164  
   165  To read the logs of a stopped pod, use:
   166  
   167  ```
   168  journalctl -m _MACHINE_ID=132f9d560e3f4d1eba8668efd488bb62
   169  
   170  [...]
   171  ```
   172  
   173  On some distributions such as Ubuntu, persistent journal storage is not enabled by default. In this case, it is not possible to get the logs of a stopped pod. Persistent journal storage can be enabled with `sudo mkdir /var/log/journal` before starting the pods.
   174  
   175  
   176  [aci-images]: https://github.com/appc/spec/blob/master/spec/aci.md#app-container-image
   177  [appc-discovery]: https://github.com/appc/spec/blob/master/spec/discovery.md#app-container-image-discovery
   178  [etcd-5449]: https://github.com/coreos/etcd/issues/5449
   179  [metadata-spec]: https://github.com/appc/spec/blob/master/spec/ace.md#app-container-metadata-service
   180  [rkt-mds]: subcommands/metadata-service.md
   181  [sd-journal]: https://www.freedesktop.org/software/systemd/man/sd-journal.html
   182  [capabilities]: capabilities-guide.md
   183  [seccomp]: seccomp-guide.md