github.com/zhuohuang-hust/src-cbuild@v0.0.0-20230105071821-c7aab3e7c840/mergeCode/runc/README.md (about)

     1  [![Build Status](https://jenkins.dockerproject.org/buildStatus/icon?job=runc Master)](https://jenkins.dockerproject.org/job/runc Master)
     2  
     3  ## runc
     4  
     5  `runc` is a CLI tool for spawning and running containers according to the OCI specification.
     6  
     7  ## Releases
     8  
     9  `runc` depends on and tracks the [runtime-spec](https://github.com/opencontainers/runtime-spec) repository.
    10  We will try to make sure that `runc` and the OCI specification major versions stay in lockstep.
    11  This means that `runc` 1.0.0 should implement the 1.0 version of the specification.
    12  
    13  You can find official releases of `runc` on the [release](https://github.com/opencontainers/runc/releases) page.
    14  
    15  ## Building
    16  
    17  `runc` currently supports the Linux platform with various architecture support. 
    18  It must be built with Go version 1.6 or higher in order for some features to function properly.
    19  
    20  In order to enable seccomp support you will need to install `libseccomp` on your platform.
    21  > e.g. `libseccomp-devel` for CentOS, or `libseccomp-dev` for Ubuntu
    22  
    23  Otherwise, if you do not want to build `runc` with seccomp support you can add `BUILDTAGS=""` when running make.
    24  
    25  ```bash
    26  # create a 'github.com/opencontainers' in your GOPATH/src
    27  cd github.com/opencontainers
    28  git clone https://github.com/opencontainers/runc
    29  cd runc
    30  
    31  make
    32  sudo make install
    33  ```
    34  
    35  `runc` will be installed to `/usr/local/sbin/runc` on your system.
    36  
    37  #### Build Tags
    38  
    39  `runc` supports optional build tags for compiling support of various features.
    40  To add build tags to the make option the `BUILDTAGS` variable must be set.
    41  
    42  ```bash
    43  make BUILDTAGS='seccomp apparmor'
    44  ```
    45  
    46  | Build Tag | Feature                            | Dependency  |
    47  |-----------|------------------------------------|-------------|
    48  | seccomp   | Syscall filtering                  | libseccomp  |
    49  | selinux   | selinux process and mount labeling | <none>      |
    50  | apparmor  | apparmor profile support           | libapparmor |
    51  | ambient   | ambient capability support         | kernel 4.3  |
    52  
    53  
    54  ### Running the test suite
    55  
    56  `runc` currently supports running its test suite via Docker.
    57  To run the suite just type `make test`.
    58  
    59  ```bash
    60  make test
    61  ```
    62  
    63  There are additional make targets for running the tests outside of a container but this is not recommended as the tests are written with the expectation that they can write and remove anywhere.
    64  
    65  You can run a specific test case by setting the `TESTFLAGS` variable.
    66  
    67  ```bash
    68  # make test TESTFLAGS="-run=SomeTestFunction"
    69  ```
    70  
    71  ## Using runc
    72  
    73  ### Creating an OCI Bundle
    74  
    75  In order to use runc you must have your container in the format of an OCI bundle.
    76  If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing Docker container.
    77  
    78  ```bash
    79  # create the top most bundle directory
    80  mkdir /mycontainer
    81  cd /mycontainer
    82  
    83  # create the rootfs directory
    84  mkdir rootfs
    85  
    86  # export busybox via Docker into the rootfs directory
    87  docker export $(docker create busybox) | tar -C rootfs -xvf -
    88  ```
    89  
    90  After a root filesystem is populated you just generate a spec in the format of a `config.json` file inside your bundle.
    91  `runc` provides a `spec` command to generate a base template spec that you are then able to edit.
    92  To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository.
    93  
    94  ```bash
    95  runc spec
    96  ```
    97  
    98  ### Running Containers
    99  
   100  Assuming you have an OCI bundle from the previous step you can execute the container in two different ways.
   101  
   102  The first way is to use the convenience command `run` that will handle creating, starting, and deleting the container after it exits.
   103  
   104  ```bash
   105  cd /mycontainer
   106  
   107  runc run mycontainerid
   108  ```
   109  
   110  If you used the unmodified `runc spec` template this should give you a `sh` session inside the container.
   111  
   112  The second way to start a container is using the specs lifecycle operations.
   113  This gives you more power over how the container is created and managed while it is running.
   114  This will also launch the container in the background so you will have to edit the `config.json` to remove the `terminal` setting for the simple examples here.
   115  Your process field in the `config.json` should look like this below with `"terminal": false` and `"args": ["sleep", "5"]`.
   116  
   117  
   118  ```json
   119          "process": {
   120                  "terminal": false,
   121                  "user": {
   122                          "uid": 0,
   123                          "gid": 0
   124                  },
   125                  "args": [
   126                          "sleep", "5"
   127                  ],
   128                  "env": [
   129                          "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
   130                          "TERM=xterm"
   131                  ],
   132                  "cwd": "/",
   133                  "capabilities": [
   134                          "CAP_AUDIT_WRITE",
   135                          "CAP_KILL",
   136                          "CAP_NET_BIND_SERVICE"
   137                  ],
   138                  "rlimits": [
   139                          {
   140                                  "type": "RLIMIT_NOFILE",
   141                                  "hard": 1024,
   142                                  "soft": 1024
   143                          }
   144                  ],
   145                  "noNewPrivileges": true
   146          },
   147  ```
   148  
   149  Now we can go though the lifecycle operations in your shell.
   150  
   151  
   152  ```bash
   153  cd /mycontainer
   154  
   155  runc create mycontainerid
   156  
   157  # view the container is created and in the "created" state
   158  runc list
   159  
   160  # start the process inside the container
   161  runc start mycontainerid
   162  
   163  # after 5 seconds view that the container has exited and is now in the stopped state
   164  runc list
   165  
   166  # now delete the container
   167  runc delete mycontainerid
   168  ```
   169  
   170  This adds more complexity but allows higher level systems to manage runc and provides points in the containers creation to setup various settings after the container has created and/or before it is deleted.
   171  This is commonly used to setup the container's network stack after `create` but before `start` where the user's defined process will be running.
   172  
   173  #### Supervisors
   174  
   175  `runc` can be used with process supervisors and init systems to ensure that containers are restarted when they exit.
   176  An example systemd unit file looks something like this.
   177  
   178  ```systemd
   179  [Unit]
   180  Description=Start My Container
   181  
   182  [Service]
   183  Type=forking
   184  ExecStart=/usr/local/sbin/runc run -d --pid-file /run/mycontainerid.pid mycontainerid
   185  ExecStopPost=/usr/local/sbin/runc delete mycontainerid
   186  WorkingDirectory=/mycontainer
   187  PIDFile=/run/mycontainerid.pid
   188  
   189  [Install]
   190  WantedBy=multi-user.target
   191  ```