github.com/opencontainers/runc@v1.2.0-rc.1.0.20240520010911-492dc558cdd6/man/runc-spec.8.md (about)

     1  % runc-spec "8"
     2  
     3  # NAME
     4  **runc-spec** - create a new specification file
     5  
     6  # SYNOPSIS
     7  **runc spec** [_option_ ...]
     8  
     9  # DESCRIPTION
    10  The **spec** command creates the new specification file named _config.json_ for
    11  the bundle.
    12  
    13  The spec generated is just a starter file. Editing of the spec is required to
    14  achieve desired results. For example, the newly generated spec includes an
    15  **args** parameter that is initially set to call the **sh** command when the
    16  container is started. Calling **sh** may work for an ubuntu container or busybox,
    17  but will not work for containers that do not include the **sh** binary.
    18  
    19  # OPTIONS
    20  **--bundle**|**-b** _path_
    21  : Set _path_ to the root of the bundle directory.
    22  
    23  **--rootless**
    24  : Generate a configuration for a rootless container. Note this option
    25  is entirely different from the global **--rootless** option.
    26  
    27  # EXAMPLES
    28  To run a simple "hello-world" container, one needs to set the **args**
    29  parameter in the spec to call hello. This can be done using **sed**(1),
    30  **jq**(1), or a text editor.
    31  
    32  The following commands will:
    33   - create a bundle for hello-world;
    34   - change the command to run in a container to **/hello** using **jq**(1);
    35   - run the **hello** command in a new hello-world container named **container1**.
    36  
    37  	mkdir hello
    38  	cd hello
    39  	docker pull hello-world
    40  	docker export $(docker create hello-world) > hello-world.tar
    41  	mkdir rootfs
    42  	tar -C rootfs -xf hello-world.tar
    43  	runc spec
    44  	jq '.process.args |= ["/hello"]' < config.json > new.json
    45  	mv -f new.json config.json
    46  	runc run container1
    47  
    48  In the **run** command above, **container1** is the name for the instance of the
    49  container that you are starting. The name you provide for the container instance
    50  must be unique on your host.
    51  
    52  An alternative for generating a customized spec config is to use
    53  **oci-runtime-tool**; its sub-command **oci-runtime-tool generate** has lots of
    54  options that can be used to do any customizations as you want. See
    55  [runtime-tools](https://github.com/opencontainers/runtime-tools) to get more
    56  information.
    57  
    58  When starting a container through **runc**, the latter usually needs root
    59  privileges. If not already running as root, you can use **sudo**(8), for
    60  example:
    61  
    62  	sudo runc start container1
    63  
    64  Alternatively, you can start a rootless container, which has the ability to run
    65  without root privileges.  For this to work, the specification file needs to be
    66  adjusted accordingly.  You can pass the **--rootless** option to this command
    67  to generate a proper rootless spec file.
    68  
    69  # SEE ALSO
    70  **runc-run**(8),
    71  **runc**(8).