diff --git a/docs/explanation/faq.md b/docs/explanation/faq.md deleted file mode 100644 index 4b66b80..0000000 --- a/docs/explanation/faq.md +++ /dev/null @@ -1,67 +0,0 @@ -(chise_faq)= - -# FAQ - -This page lists some known limitations and frequently asked questions. - - -(faq_arbitrary_package_names)= - -## Is it possible to use arbitrary package names? - -No, package names must be the same as the package names in the archive, so that -there's a single namespace to remember and respect. - - -(faq_available_ubuntu_versions)= - -## Which Ubuntu versions have package slices? - -The slice definitions are located at the {{chisel_releases_repo}}. The -`ubuntu-XX.YY` branches in that repository contain the slice definitions for -the corresponding Ubuntu releases. - -If you find a specific release missing, let the maintainers know by [creating a -new issue] in the {{chisel_releases_repo}}. - - -(faq_non-ubuntu_archives)= - -## Is it possible to use non-Ubuntu archives? - -No. The supported archives are described at -{ref}`chisel_yaml_format_spec_archives`. - - -(faq_ppa)= - -## Is it possible to use PPAs? - -Not at the moment. - - -(faq_file_ownership_preserved)= - -## Is file ownership preserved? - -No, Chisel does not yet preserve the owner UID:GID of files extracted from -packages. The owner of the extracted files is the current user. - - -(faq_reproducible_output)= - -## Does Chisel support reproducible rootfs outputs? - -Chisel always fetches the latest version of a package from the archives. Thus, -the root file systems Chisel produces in subsequent executions may not be -identical if a package has changed in the meantime. - -Chisel also does not support pinning package versions. - -Related: [Issue 154]. - - - - -[creating a new issue]: https://github.com/canonical/chisel-releases/issues/new -[Issue 154]: https://github.com/canonical/chisel/issues/154 diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 48e627b..756bebb 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -9,7 +9,6 @@ Chisel was created to build a minimal, secure Ubuntu root file systems. :maxdepth: 1 mode-of-operation -faq ``` ## Package slices Slices are defined via slice definition files and follow naming conventions. diff --git a/docs/explanation/mode-of-operation.md b/docs/explanation/mode-of-operation.md index 6fa067e..90e39b6 100644 --- a/docs/explanation/mode-of-operation.md +++ b/docs/explanation/mode-of-operation.md @@ -69,7 +69,9 @@ the corresponding package tarballs. Chisel groups and merges all slice definitions per package. Then, for every package, it extracts the **specified slices' paths** into -the provided root file system. +the provided root file system. Files ownership (UID:GID) is not +preserved during this process. The owner of the extracted files +is the current user. diff --git a/docs/reference/chisel-releases/chisel.yaml.md b/docs/reference/chisel-releases/chisel.yaml.md index e2768ac..d0cbd88 100644 --- a/docs/reference/chisel-releases/chisel.yaml.md +++ b/docs/reference/chisel-releases/chisel.yaml.md @@ -79,7 +79,7 @@ Tells Chisel which Ubuntu archives to fetch packages from. ```{note} Chisel only supports fetching packages from the official Ubuntu archives, -including ESM. +including ESM. The use of PPAs is not supported at the moment. ``` For example: diff --git a/docs/reference/chisel-releases/index.md b/docs/reference/chisel-releases/index.md index 15eacea..e3aeae0 100644 --- a/docs/reference/chisel-releases/index.md +++ b/docs/reference/chisel-releases/index.md @@ -11,6 +11,9 @@ named `chisel.yaml` form what is called a _chisel-release_. The {{chisel_releases_repo}} contains a number of branches for various _chisel-releases_, matching the corresponding Ubuntu releases. +If you find a specific release missing, let the maintainers know by [creating a +new issue] in the {{chisel_releases_repo}}. + A _chisel-release_ is simply a directory with the following structure: @@ -30,3 +33,6 @@ The following pages provide more details on: chisel.yaml slice-definitions ``` + +[creating a +new issue]: https://github.com/canonical/chisel-releases/issues/new diff --git a/docs/reference/chisel-releases/slice-definitions.md b/docs/reference/chisel-releases/slice-definitions.md index 32d2572..811cb13 100644 --- a/docs/reference/chisel-releases/slice-definitions.md +++ b/docs/reference/chisel-releases/slice-definitions.md @@ -34,13 +34,21 @@ Although the `hello.yaml` file can be placed in a sub-directory of `slices/` e.g Indicates the package name. It must follow the [Debian policy for package name](https://www.debian.org/doc/debian-policy/ch-binary.html#the-package-name). +The use of arbitrary package names is not allowed; the names must be the +same as the package names in the archive to maintain a single namespace +to remember and respect. + +Chisel does not support pinning package versions. Chisel always fetches +the latest version of a package from the archives. Thus, the root file +systems Chisel produces in subsequent executions may not be identical if +a package has changed in the meantime. + As indicated above, the value must also match the YAML file basename. For example: ```yaml package: hello ``` - (slice_definitions_format_archive)= ### `archive` @@ -56,6 +64,7 @@ fetched from. If specified, Chisel fetches this package from that archive despit {ref}`chisel_yaml_format_spec_archives_priority` settings in {ref}`chisel_yaml_ref`. + The archive name must be defined in {ref}`chisel_yaml_format_spec_archives`. For example: