github.com/jaypipes/ghw@v0.21.1/SNAPSHOT.md (about)

     1  # ghw snapshots
     2  
     3  For ghw, snapshots are partial clones of the `/proc`, `/sys` (et. al.) subtrees copied from arbitrary
     4  machines, which ghw can consume later. "partial" is because the snapshot doesn't need to contain a
     5  complete copy of all the filesystem subtree (that is doable but inpractical). It only needs to contain
     6  the paths ghw cares about. The snapshot concept was introduced [to make ghw easier to test](https://github.com/jaypipes/ghw/issues/66).
     7  
     8  ## Create and consume snapshot
     9  
    10  The recommended way to create snapshots for ghw is to use the `ghw-snapshot` tool.
    11  This tool is maintained by the ghw authors, and snapshots created with this tool are guaranteed to work.
    12  
    13  To consume the ghw snapshots, please check the `README.md` document.
    14  
    15  ## Snapshot design and definitions
    16  
    17  The remainder of this document will describe how a snapshot looks like and provides rationale for all the major design decisions.
    18  Even though this document aims to provide all the necessary information to understand how ghw creates snapshots and what you should
    19  expect, we recommend to check also the [project issues](https://github.com/jaypipes/ghw/issues) and the `git` history to have the full picture.
    20  
    21  ### Scope
    22  
    23  ghw supports snapshots only on linux platforms. This restriction may be lifted in future releases.
    24  Snapshots must be consumable in the following supported ways:
    25  
    26  1. (way 1) from docker (or podman), mounting them as volumes. See `hack/run-against-snapshot.sh`
    27  2. (way 2) using the environment variables `GHW_SNAPSHOT_*`. See `README.md` for the full documentation.
    28  
    29  Other combinations are possible, but are unsupported and may stop working any time.
    30  You should depend only on the supported ways to consume snapshots.
    31  
    32  ### Snapshot content constraints
    33  
    34  Stemming from the use cases, the snapshot content must have the following properties:
    35  
    36  0. (constraint 0) MUST contain the same information as live system (obviously). Whatever you learn from a live system, you MUST be able to learn from a snapshot.
    37  1. (constraint 1) MUST NOT require any post processing before it is consumable besides, obviously, unpacking the `.tar.gz` on the right directory - and pointing ghw to that directory.
    38  2. (constraint 2) MUST NOT require any special handling nor special code path in ghw. From ghw perspective running against a live system or against a snapshot should be completely transparent.
    39  3. (constraint 3) MUST contain only data - no executable code is allowed ever. This makes snapshots trivially safe to share and consume.
    40  4. (constraint 4) MUST NOT contain any personally-identifiable data. Data gathered into a snapshot is for testing and troubleshooting purposes and should be safe to send to troubleshooters to analyze.
    41  
    42  It must be noted that trivially cloning subtrees from `/proc` and `/sys` and creating a tarball out of them doesn't work
    43  because both pseudo filesystems make use of symlinks, and [docker doesn't really play nice with symlinks](https://github.com/jaypipes/ghw/commit/f8ffd4d24e62eb9017511f072ccf51f13d4a3399).
    44  This conflcits with (way 1) above.
    45