github.com/opencontainers/umoci@v0.4.8-0.20240508124516-656e4836fb0d/doc/man/umoci-insert.1.md (about)

     1  % umoci-insert(1) # umoci insert - insert content into an OCI image
     2  % Aleksa Sarai
     3  % SEPTEMBER 2018
     4  # NAME
     5  umoci insert - insert content into an OCI image
     6  
     7  # SYNOPSIS
     8  **umoci insert**
     9  **--image**=*image*[:*tag*]
    10  [**--tag**=*new-tag*]
    11  [**--opaque**]
    12  [**--rootless**]
    13  [**--uid-map**=*value*]
    14  [**--uid-map**=*value*]
    15  [**--no-history**]
    16  [**--history.comment**=*comment*]
    17  [**--history.created_by**=*created_by*]
    18  [**--history.author**=*author*]
    19  [**--history-created**=*date*]
    20  *source*
    21  *target*
    22  
    23  **umoci insert**
    24  [options]
    25  **--whiteout**
    26  *target*
    27  
    28  
    29  # DESCRIPTION
    30  In the first form, insert the contents of *source* into the OCI image given by
    31  **--image** -- **overwriting it unless you specify --tag**. This is done by
    32  creating a new layer containing just the contents of *source* with a name of
    33  *target*. *source* can be either a file or directory, and in the latter case it
    34  will be recursed. If **--opaque** is specified then any paths below *target* in
    35  the previous image layers (assuming *target* is a directory) will be removed.
    36  
    37  In the second form, inserts a "deletion entry" into the OCI image for *target*
    38  inside the image. This is done by inserting a layer containing just a whiteout
    39  entry for the given path.
    40  
    41  Note that this command works by creating a new layer, so this should not be
    42  used to remove (or replace) secrets from an already-built image. See
    43  **umoci-config**(1) and **--config.volume** for how to achieve this correctly
    44  by not creating image layers with secrets in the first place.
    45  
    46  If **--no-history** was not specified, a history entry is appended to the
    47  tagged OCI image for this change (with the various **--history.** flags
    48  controlling the values used). To view the history, see **umoci-stat**(1).
    49  
    50  # OPTIONS
    51  The global options are defined in **umoci**(1).
    52  
    53  **--image**=*image*[:*tag*]
    54    The source and destination tag for the insertion of *file* at *path* inside
    55    the container image. *image* must be a path to a valid OCI image and *tag*
    56    must be a valid tag in the image. If *tag* is not provided it defaults to
    57    "latest".
    58  
    59  **--tag**=*new-tag*
    60    Tag name for the modified image, if unspecified then the original tag
    61    provided to **--image** will be clobbered.
    62  
    63  **--opaque**
    64    (Assuming *target* is a directory.) Add an opaque whiteout entry for *target*
    65    so that any child path of *target* in previous layers is masked by the new
    66    entry for *target*, which will just contain the contents of *source*. This
    67    allows for the complete replacement of a directory, as opposed to the merging
    68    of directory entries.
    69  
    70  **--whiteout**
    71    Add a deletion entry for *target*, so that it is not present in future
    72    extractions of the image.
    73  
    74  **--rootless**
    75    Enable rootless insertion support. This allows for **umoci-insert**(1) to be
    76    used as an unprivileged user. Use of this flag implies **--uid-map=0:$(id
    77    -u):1** and **--gid-map=0:$(id -g):1**, as well as enabling several features
    78    to fake parts of the recursion process in an attempt to generate an
    79    as-close-as-possible clone of the filesystem for insertion.
    80  
    81  **--uid-map**=*value*
    82    Specifies a UID mapping to use when inserting files. This is used in a
    83    similar fashion to **user_namespaces**(7), and is of the form
    84    **container:host[:size]**.
    85  
    86  **--gid-map**=*value*
    87    Specifies a GID mapping to use when inserting files. This is used in a
    88    similar fashion to **user_namespaces**(7), and is of the form
    89    **container:host[:size]**.
    90  
    91  **--no-history**
    92    Causes no history entry to be added for this operation. **This is not
    93    recommended for use with umoci-insert(1), since it results in the history not
    94    including all of the image layers -- and thus will cause confusion with tools
    95    that look at image history.**
    96  
    97  **--history.comment**=*comment*
    98    Comment for the history entry corresponding to this modification of the image
    99    If unspecified, **umoci**(1) will generate an implementation-dependent value.
   100  
   101  **--history.created_by**=*created_by*
   102    CreatedBy entry for the history entry corresponding to this modification of
   103    the image. If unspecified, **umoci**(1) will generate an
   104    implementation-dependent value.
   105  
   106  **--history.author**=*author*
   107    Author value for the history entry corresponding to this modification of the
   108    image. If unspecified, this value will be the image's author value **after**
   109    any modifications were made by this call of **umoci-config**(1).
   110  
   111  **--history-created**=*date*
   112    Creation date for the history entry corresponding to this modifications of
   113    the image. This must be an ISO8601 formatted timestamp (see **date**(1)). If
   114    unspecified, the current time is used.
   115  
   116  # EXAMPLE
   117  
   118  The following inserts a file `mybinary` into the path `/usr/bin/mybinary` and a
   119  directory `myconfigdir` into the path `/etc/myconfigdir`. It should be noted
   120  that if `/etc/myconfigdir` already exists in the image, the contents of the two
   121  directories are merged (with the newer layer taking precedence).
   122  
   123  ```
   124  % umoci insert --image oci:foo mybinary /usr/bin/mybinary
   125  % umoci insert --image oci:foo myconfigdir /etc/myconfigdir
   126  ```
   127  
   128  And in these examples we delete `/usr/bin/mybinary` and replace the entirety of
   129  `/etc` with `myetcdir` (such that none of the old `/etc` entries will be
   130  present on **umoci-unpack**(1)).
   131  
   132  ```
   133  % umoci insert --image oci:foo --whiteout /usr/bin/mybinary
   134  % umoci insert --image oci:foo --opaque myetcdir /etc
   135  ```
   136  
   137  # SEE ALSO
   138  **umoci**(1), **umoci-repack**(1), **umoci-raw-add-layer**(1)