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