├── .github └── workflows │ ├── automatic-doc-checks.yml │ ├── markdown-style-checks.yml │ ├── periodic-style-checks.yml │ └── sphinx-python-dependency-build-checks.yml ├── .gitignore ├── README.rst └── docs ├── .custom_wordlist.txt ├── .gitignore ├── .readthedocs.yaml ├── .sphinx ├── .markdownlint.json ├── .wordlist.txt ├── _static │ ├── css │ │ └── pdf.css │ ├── favicon.png │ └── tag.png ├── _templates │ └── header.html ├── fonts │ ├── LICENCE.txt │ ├── Ubuntu-B.ttf │ ├── Ubuntu-R.ttf │ ├── Ubuntu-RI.ttf │ ├── UbuntuMono-B.ttf │ ├── UbuntuMono-R.ttf │ └── UbuntuMono-RI.ttf ├── get_vale_conf.py ├── images │ ├── Canonical-logo-4x.png │ ├── front-page-light.pdf │ └── normal-page-footer.pdf ├── latex_elements_template.txt ├── metrics │ ├── build_metrics.sh │ └── source_metrics.sh ├── pa11y.json ├── requirements.txt └── spellingcheck.yaml ├── Makefile ├── conf.py ├── contributing.md ├── explanation ├── community-engagement.md ├── core-elements │ ├── index.md │ ├── inside-ubuntu-core.md │ ├── snaps-in-ubuntu-core.md │ └── storage-layout.md ├── docker-companion-snap.md ├── full-disk-encryption.md ├── how-installation-works.md ├── index.md ├── preseed-performance.md ├── recovery-modes.md ├── refresh-control.md ├── remodelling.md ├── security-and-sandboxing.md ├── stores │ ├── brand-accounts.md │ ├── dedicated-snap-store.md │ ├── index.md │ ├── store-overview.md │ └── store-scoping.md └── system-snaps │ ├── bluetooth │ ├── bluetooth-snaps.md │ ├── commands.md │ ├── index.md │ ├── kernel-configuration.md │ └── pairing.md │ ├── index.md │ ├── modem-manager │ ├── 1 │ ├── debug.md │ ├── index.md │ ├── install-modem-manager.md │ ├── release-notes.md │ └── using-modem-manager.md │ └── network-manager │ ├── how-to-guides │ ├── configure-cellular-connections.md │ ├── configure-shared-connections.md │ ├── configure-the-snap │ │ ├── connectivity-check.md │ │ ├── debug.md │ │ ├── default-renderer.md │ │ ├── index.md │ │ ├── wake-on-wlan.md │ │ └── wifi-powersave.md │ ├── configure-vpn-connections.md │ ├── configure-wifi-access-points.md │ ├── configure-wifi-connections.md │ ├── edit-connections.md │ ├── explore-network-status.md │ ├── index.md │ ├── message-logging.md │ ├── networkmanager-and-netplan.md │ └── routing-tables.md │ ├── index.md │ ├── install-networkmanager.md │ ├── release-notes.md │ └── report-a-bug.md ├── how-to-guides ├── container-deployment │ ├── build-an-image-for-docker-deployment.md │ ├── deploy-docker-from-a-snap.md │ ├── index.md │ ├── package-docker-images-in-a-snap.md │ └── run-a-docker-container.md ├── image-creation │ ├── add-a-splash-screen.md │ ├── add-console-conf.md │ ├── add-custom-snaps.md │ ├── board-enablement.md │ ├── build-a-gadget-snap.md │ ├── build-a-kernel-snap.md │ ├── calculate-partition-sizes.md │ ├── index.md │ ├── optimise-boot-speed.md │ └── use-ubuntu-image.md ├── index.md ├── manage-ubuntu-core │ ├── add-a-system-user.md │ ├── create-a-recovery-system-from-the-api.md │ ├── index.md │ ├── modify-kernel-options.md │ ├── set-system-options.md │ ├── set-system-time.md │ ├── test-on-qemu.md │ ├── troubleshooting.md │ ├── upgrade-ubuntu-core.md │ ├── use-a-recovery-mode.md │ └── use-ubuntu-one-ssh.md └── using-ubuntu-core.md ├── index.md ├── redirects.txt ├── reference ├── assertions │ ├── account-key.md │ ├── account.md │ ├── confdb-schema.md │ ├── index.md │ ├── model.md │ ├── repair.md │ ├── serial.md │ ├── snap-build.md │ ├── snap-declaration.md │ ├── snap-resource-pair.md │ ├── snap-resource-revision.md │ ├── snap-revision.md │ ├── store.md │ ├── system-user.md │ ├── validation-set.md │ └── validation.md ├── gadget-snap-format.md ├── index.md ├── kernel-boot-parameters.md ├── release-notes.md ├── system-requirements.md └── testing-platforms.md ├── requirements.txt ├── reuse └── links.txt ├── tutorials ├── build-your-first-image │ ├── access-ubuntu-one.md │ ├── boot-the-image.md │ ├── build-the-image.md │ ├── create-a-model.md │ ├── index.md │ ├── requirements.md │ └── sign-the-model.md ├── index.md └── try-pre-built-images │ ├── index.md │ ├── install-on-a-device │ ├── index.md │ ├── install-on-renesas.md │ ├── use-raspberry-pi-imager.md │ └── use-the-dd-command.md │ └── install-on-a-vm.md └── warnings.txt /.github/workflows/automatic-doc-checks.yml: -------------------------------------------------------------------------------- 1 | # 2 | name: Automatic doc checks 3 | 4 | on: 5 | push: 6 | branches: [ main ] 7 | pull_request: 8 | paths: 9 | - 'docs/**' # Only run on changes to the docs directory 10 | 11 | workflow_dispatch: 12 | # Manual trigger 13 | 14 | 15 | concurrency: 16 | group: ${{ github.workflow }}-${{ github.ref }} 17 | cancel-in-progress: true 18 | 19 | jobs: 20 | documentation-checks: 21 | uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main 22 | with: 23 | working-directory: "docs" 24 | fetch-depth: 0 25 | -------------------------------------------------------------------------------- /.github/workflows/markdown-style-checks.yml: -------------------------------------------------------------------------------- 1 | name: Markdown style checks 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | paths: 8 | - 'docs/**' # Only run on changes to the docs directory 9 | pull_request: 10 | branches: 11 | - '*' 12 | paths: 13 | - 'docs/**' # Only run on changes to the docs directory 14 | 15 | jobs: 16 | markdown-lint: 17 | runs-on: ubuntu-22.04 18 | steps: 19 | - uses: actions/checkout@v4 20 | with: 21 | fetch-depth: 0 22 | - uses: DavidAnson/markdownlint-cli2-action@v16 23 | with: 24 | config: "docs/.sphinx/.markdownlint.json" 25 | -------------------------------------------------------------------------------- /.github/workflows/periodic-style-checks.yml: -------------------------------------------------------------------------------- 1 | name: Periodic Style Checks 2 | 3 | on: 4 | schedule: 5 | - cron: "0 1 * * 4" # Runs at 01:00 AM on every Wednesday 6 | 7 | jobs: 8 | vale: 9 | name: Style checker 10 | runs-on: ubuntu-22.04 11 | defaults: 12 | run: 13 | shell: bash 14 | working-directory: "sp-docs" 15 | steps: 16 | - uses: actions/checkout@v4 17 | - name: Run vale 18 | run: | 19 | make vale 20 | -------------------------------------------------------------------------------- /.github/workflows/sphinx-python-dependency-build-checks.yml: -------------------------------------------------------------------------------- 1 | # The purpose of this workflow file is to confirm that the Sphinx 2 | # virtual environment can be built from source, consequently documenting 3 | # the packages required in the build environment to do that. 4 | # 5 | # This is needed because some projects embeds the documentation into built 6 | # artifacts which involves rendering the documentation on the target 7 | # architecture. 8 | # 9 | # Depending on the architecture, pip may or may not have already built wheels 10 | # available, and as such we need to make sure building wheels from source can 11 | # succeed. 12 | name: Sphinx python dependency build checks 13 | 14 | on: 15 | push: 16 | branches: [ main ] 17 | pull_request: 18 | workflow_dispatch: # manual trigger 19 | 20 | concurrency: 21 | group: ${{ github.workflow }}-${{ github.ref }} 22 | cancel-in-progress: true 23 | 24 | jobs: 25 | build: 26 | name: build 27 | runs-on: ubuntu-latest 28 | steps: 29 | - name: Checkout code 30 | uses: actions/checkout@v4 31 | 32 | - name: Install dependencies 33 | run: | 34 | set -ex 35 | sudo apt-get --fix-missing update 36 | sudo apt -y install \ 37 | cargo \ 38 | libpython3-dev \ 39 | libxml2-dev \ 40 | libxslt1-dev \ 41 | make \ 42 | python3-venv \ 43 | rustc \ 44 | libtiff5-dev libjpeg8-dev libopenjp2-7-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python3-tk libharfbuzz-dev libfribidi-dev libxcb1-dev 45 | - name: Build Sphinx venv 46 | working-directory: "docs" 47 | run: | 48 | set -ex 49 | make install \ 50 | PIPOPTS="--no-binary :all:" \ 51 | || ( cat .sphinx/venv/pip_install.log && exit 1 ) 52 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/.gitignore -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Ubuntu Core documentation 2 | ========================= 3 | 4 | This repository contains the source files to build the Ubuntu Core documentation, which is published here: 5 | 6 | https://ubuntu.com/core/docs 7 | 8 | The documentation is written in Markdown and built with Sphinx, all taken from the `Documentation starter pack`_. 9 | 10 | Build the documentation 11 | ----------------------- 12 | 13 | Install prerequisite software 14 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 15 | 16 | To install the prerequisites: 17 | 18 | .. code-block:: none 19 | 20 | make install 21 | 22 | This will create a virtual environment (``.sphinx/venv``) and install 23 | dependency software (``.sphinx/requirements.txt``) within it. 24 | 25 | View the documentation 26 | ~~~~~~~~~~~~~~~~~~~~~~ 27 | 28 | To view the documentation: 29 | 30 | .. code-block:: none 31 | 32 | make run 33 | 34 | This will do several things: 35 | 36 | * activate the virtual environment 37 | * build the documentation 38 | * serve the documentation on **127.0.0.1:8000** 39 | * rebuild the documentation each time a file is saved 40 | * send a reload page signal to the browser when the documentation is rebuilt 41 | 42 | The ``run`` target is therefore very convenient when preparing to submit a 43 | change to the documentation. 44 | 45 | .. LINKS 46 | .. _`Documentation starter pack`: https://github.com/canonical/sphinx-docs-starter-pack/tree/main 47 | 48 | -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | 2 | # Starter pack rules start here 3 | 4 | # Environment 5 | /*env*/ 6 | .sphinx/venv/ 7 | 8 | # Sphinx 9 | .sphinx/warnings.txt 10 | .sphinx/.wordlist.dic 11 | .sphinx/.doctrees/ 12 | .sphinx/node_modules/ 13 | 14 | # Vale 15 | .sphinx/styles/* 16 | .sphinx/vale.ini 17 | 18 | # Build outputs 19 | _build 20 | 21 | # Node.js 22 | package*.json 23 | 24 | # Unrelated cache and config files 25 | .DS_Store 26 | __pycache__ 27 | .idea/ 28 | .vscode/ 29 | -------------------------------------------------------------------------------- /docs/.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yaml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: 2 7 | 8 | # Set the version of Python and other tools you might need 9 | build: 10 | os: ubuntu-22.04 11 | tools: 12 | python: "3.11" 13 | jobs: 14 | post_checkout: 15 | - git fetch --unshallow || true 16 | # Cancel building pull requests when there aren't changed in the docs directory. 17 | # If there are no changes (git diff exits with 0) we force the command to return with 183. 18 | # This is a special exit code on Read the Docs that will cancel the build immediately. 19 | # https://docs.readthedocs.io/en/stable/build-customization.html#cancel-build-based-on-a-condition 20 | - | 21 | if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- 'docs/' '.readthedocs.yaml'; 22 | then 23 | exit 183; 24 | fi 25 | 26 | # Build documentation in the docs/ directory with Sphinx 27 | sphinx: 28 | builder: dirhtml 29 | configuration: docs/conf.py 30 | fail_on_warning: false 31 | 32 | # If using Sphinx, optionally build your docs in additional formats such as PDF 33 | # formats: 34 | # - pdf 35 | 36 | # Optionally declare the Python requirements required to build your docs 37 | python: 38 | install: 39 | - requirements: docs/requirements.txt 40 | -------------------------------------------------------------------------------- /docs/.sphinx/.markdownlint.json: -------------------------------------------------------------------------------- 1 | { 2 | "default": false, 3 | "MD003": { 4 | "style": "atx" 5 | }, 6 | "MD013": { 7 | "code_blocks": false, 8 | "tables": false, 9 | "stern": true, 10 | "line_length": 150 11 | }, 12 | "MD014": true, 13 | "MD018": true, 14 | "MD022": true, 15 | "MD023": true, 16 | "MD026": { 17 | "punctuation": ".,;。，；" 18 | }, 19 | "MD031": { 20 | "list_items": false 21 | }, 22 | "MD032": true, 23 | "MD035": true, 24 | "MD042": true, 25 | "MD045": true, 26 | "MD052": true 27 | } -------------------------------------------------------------------------------- /docs/.sphinx/.wordlist.txt: -------------------------------------------------------------------------------- 1 | ACME 2 | ACME's 3 | addons 4 | AGPLv 5 | API 6 | APIs 7 | balancer 8 | Charmhub 9 | CLI 10 | DCO 11 | Diátaxis 12 | Dqlite 13 | dropdown 14 | EBS 15 | EKS 16 | enablement 17 | favicon 18 | Furo 19 | Git 20 | GitHub 21 | Grafana 22 | IAM 23 | installable 24 | JSON 25 | Juju 26 | Kubeflow 27 | Kubernetes 28 | Launchpad 29 | linter 30 | LTS 31 | LXD 32 | Makefile 33 | Makefiles 34 | Matrix 35 | Mattermost 36 | MicroCeph 37 | MicroCloud 38 | MicroOVN 39 | MyST 40 | namespace 41 | namespaces 42 | NodePort 43 | Numbat 44 | observability 45 | OEM 46 | OLM 47 | Permalink 48 | pre 49 | Quickstart 50 | ReadMe 51 | reST 52 | reStructuredText 53 | roadmap 54 | RTD 55 | subdirectories 56 | subfolders 57 | subtree 58 | TODO 59 | Ubuntu 60 | UI 61 | UUID 62 | VM 63 | webhook 64 | YAML 65 | -------------------------------------------------------------------------------- /docs/.sphinx/_static/css/pdf.css: -------------------------------------------------------------------------------- 1 | /* Only relevant for specific PDF generation issues */ 2 | 3 | .rubric>.hclass2 { 4 | display: block; 5 | font-size: 2em; 6 | border-radius: .5rem; 7 | font-weight: 300; 8 | line-height: 1.25; 9 | margin-top: 1.75rem; 10 | margin-right: -0.5rem; 11 | margin-bottom: 0.5rem; 12 | margin-left: -0.5rem; 13 | padding-left: .5rem; 14 | padding-right: .5rem; 15 | } -------------------------------------------------------------------------------- /docs/.sphinx/_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/_static/favicon.png -------------------------------------------------------------------------------- /docs/.sphinx/_static/tag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/_static/tag.png -------------------------------------------------------------------------------- /docs/.sphinx/_templates/header.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-B.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/Ubuntu-B.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-R.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/Ubuntu-R.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-RI.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/Ubuntu-RI.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-B.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/UbuntuMono-B.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-R.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/UbuntuMono-R.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-RI.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/fonts/UbuntuMono-RI.ttf -------------------------------------------------------------------------------- /docs/.sphinx/get_vale_conf.py: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env python 2 | 3 | import requests 4 | import os 5 | 6 | DIR = os.getcwd() 7 | 8 | 9 | def main(): 10 | if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): 11 | print("Vale directory exists") 12 | else: 13 | os.makedirs(f"{DIR}/.sphinx/styles/Canonical") 14 | 15 | url = ( 16 | "https://api.github.com/repos/canonical/praecepta/" 17 | + "contents/styles/Canonical" 18 | ) 19 | r = requests.get(url) 20 | for item in r.json(): 21 | download = requests.get(item["download_url"]) 22 | file = open(".sphinx/styles/Canonical/" + item["name"], "w") 23 | file.write(download.text) 24 | file.close() 25 | 26 | if os.path.exists(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical"): 27 | print("Vocab directory exists") 28 | else: 29 | os.makedirs(f"{DIR}/.sphinx/styles/config/vocabularies/Canonical") 30 | 31 | url = ( 32 | "https://api.github.com/repos/canonical/praecepta/" 33 | + "contents/styles/config/vocabularies/Canonical" 34 | ) 35 | r = requests.get(url) 36 | for item in r.json(): 37 | download = requests.get(item["download_url"]) 38 | file = open( 39 | ".sphinx/styles/config/vocabularies/Canonical/" + item["name"], 40 | "w" 41 | ) 42 | file.write(download.text) 43 | file.close() 44 | config = requests.get( 45 | "https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini" 46 | ) 47 | file = open(".sphinx/vale.ini", "w") 48 | file.write(config.text) 49 | file.close() 50 | 51 | 52 | if __name__ == "__main__": 53 | main() 54 | -------------------------------------------------------------------------------- /docs/.sphinx/images/Canonical-logo-4x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/images/Canonical-logo-4x.png -------------------------------------------------------------------------------- /docs/.sphinx/images/front-page-light.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/images/front-page-light.pdf -------------------------------------------------------------------------------- /docs/.sphinx/images/normal-page-footer.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/.sphinx/images/normal-page-footer.pdf -------------------------------------------------------------------------------- /docs/.sphinx/metrics/build_metrics.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # shellcheck disable=all 3 | 4 | links=0 5 | images=0 6 | 7 | # count number of links 8 | links=$(find . -type d -path './.sphinx' -prune -o -name '*.html' -exec cat {} + | grep -o " 22 | Storage layout 23 | Snaps in Ubuntu Core 24 | -------------------------------------------------------------------------------- /docs/explanation/docker-companion-snap.md: -------------------------------------------------------------------------------- 1 | (explanation-docker-companion-snap)= 2 | # Docker companion snap 3 | 4 | A Docker companion snap is a package with instructions and artifacts for deploying a Docker Container. 5 | 6 | This snap orchestrates the workflow by communicating with a Docker Engine on the host machine. 7 | 8 | Companion snaps are most useful when creating self-contained Ubuntu Core images that boot into a production state without manual intervention. 9 | 10 | This is achieved by building a [custom Ubuntu Core image](/tutorials/build-your-first-image/index) that includes the companion snap along with the [Docker Engine](https://snapcraft.io/docker). 11 | 12 | The Ubuntu Core image can also include the application configurations if they aren't sourced from remote media. 13 | 14 | While Docker companion snaps are primarily designed for Ubuntu Core, they can also operate in other snap-enabled environments. The main dependencies for it are _snapd_ and Docker Engine. 15 | 16 | A companion snap contains one or more apps, just like any other snap. 17 | The app responsible for the container contains a set of instructions passed over to the Docker Engine via a POSIX or TCP socket. 18 | It is the Docker Engine that manages the container's runtime, not the snap. 19 | 20 | The companion snap can bundle the container image and handle the container's data, logging, and configurations. 21 | 22 | The snap ecosystem enhances Docker deployments with features like transactional updates, rollback, over-the-air (OTA) management, in both internet-connected and air-gapped environments. 23 | 24 | For more information on creating Docker companion snaps, refer to [Deploy Docker containers from a snap](/how-to-guides/container-deployment/deploy-docker-from-a-snap). 25 | 26 | -------------------------------------------------------------------------------- /docs/explanation/how-installation-works.md: -------------------------------------------------------------------------------- 1 | (explanation-how-installation-works)= 2 | # How installation works 3 | 4 | The Ubuntu Core install image is composed from the kernel, gadget, base, snapd and app snaps (see [Snaps in Ubuntu Core](/explanation/core-elements/snaps-in-ubuntu-core) for further details). The resultant image typically contains the following: 5 | 6 | ![Core install image partition](https://assets.ubuntu.com/v1/108d3dba-core-install-image-partition.png) 7 | 8 | Any device booting an Ubuntu Core installation image will create or use the partitions defined by its [Storage layout](/explanation/core-elements/storage-layout) and proceed through the following installation steps. 9 | 10 | The first three (1-3) are also described in the [recovery mode](/explanation/recovery-modes) boot process: 11 | 12 | 1. Boot through the bootloader, its assets, and boot configuration in `ubuntu-seed`. 13 | 1. Bootloader loads the kernel from a designated [recovery system](/explanation/recovery-modes). 14 | 1. Kernel initialises the system and runs the snaps from that system in **install mode**. At this point, the system is running from tmpfs in an ephemeral state with all snaps from the recovery system model marked for use in install mode (as indicated by the modes field values), including the _snapd_ snap, the gadget snap, the kernel snap and the base snap (usually the _core20_ snap). 15 | 1. The snapd snap proceeds to install the actual run mode system by: 16 | - creating all missing partitions. 17 | - (*optionally*) encrypting `ubuntu-data` and `ubuntu-save` if supported and not disabled. 18 | - sealing the disk keys through hardware support. 19 | - setting up the run system in `ubuntu-data`. 20 | - setting boot configuration and the run mode kernel in `ubuntu-boot` for run mode. 21 | 1. snapd proceeds to reboot into **run mode**. 22 | 1. From run mode, snapd bootstraps itself and proceeds to _seeding_, installing and activating all the snaps marked for **run mode** use in the recovery system. 23 | 24 | ## The install-device hook 25 | 26 | A [gadget](/reference/gadget-snap-format) can optionally define an _install-device hook_ . This is invoked from **install mode** before rebooting into **run mode**, between steps 4 and 5 above, and also after a [factory reset](/explanation/recovery-modes.md#factory-reset), to perform early hardware and firmware configuration. 27 | 28 | The [snapctl system-mode](https://snapcraft.io/docs/using-snapctl#heading--system-mode) command can be run during execution of the hook to detect which mode the install-device hook has been executed under. 29 | 30 | All partitions are created and mounted when the install-device hook runs. 31 | 32 | If applicable, precautions should be taken to ensure that any sensitive configuration is idempotent and/or only done once for the lifetime of the device. 33 | 34 | The install-device hook can also stop the subsequent reboot from booting into *run mode* (step 5, above) with the _[snapctl](https://snapcraft.io/docs/using-snapctl) reboot_ command and either `--halt` or `--poweroff` arguments: 35 | 36 | ``` 37 | snapctl reboot --halt|--poweroff 38 | ``` 39 | Either reboot command will only take effect after the hook has finished. 40 | 41 | ## Factory image hint 42 | 43 | A Ubuntu Core image can be built to include a _hint_ that an image is intended to be used, or first booted, in the device factory. This hint can then be used to govern whether factory-only resources are accessible, for instance, but no security-related decisions should be made based solely on its inclusion as it could be possible for the hint to be set again in the field. 44 | 45 | The factory image hint is set by adding `--factory-image` to the _ubuntu-image_ command when building the image: 46 | 47 | ``` 48 | ubuntu-image snap my-model.model --factory-image 49 | ``` 50 | 51 | See [Building the image](/tutorials/build-your-first-image/index) for details on how images are built. 52 | 53 | The factory image hint is cleared directly before rebooting into **run mode**. 54 | 55 | For the current boot, the state of the factory image hint can be viewed by invoking `snapctl system-mode` and checking whether `factory: true` is included in its YAML output. See [The snapctl tool](https://snapcraft.io/docs/using-snapctl) for more information. 56 | 57 | -------------------------------------------------------------------------------- /docs/explanation/index.md: -------------------------------------------------------------------------------- 1 | # Explanation 2 | 3 | 4 | Our explanatory and conceptual guides are written to provide a better understanding of how Ubuntu Core works and how it can be used and configured. They enable you to expand your knowledge and become better at Ubuntu Core. 5 | 6 | ## Operations 7 | 8 | Understanding how certain operations work in Ubuntu Core is key to getting the most out of the system. 9 | 10 | - [How installation works](how-installation-works) 11 | - [Refresh control](refresh-control) 12 | - [Remodelling](remodelling) 13 | - [Preseed performance](preseed-performance) 14 | - [Recovery modes](recovery-modes) 15 | - [Docker companion snap](docker-companion-snap) 16 | 17 | ## Security 18 | 19 | A devices data and runtime environment is secure and isolated from other applications and devices. 20 | 21 | - [Security and sandboxing](security-and-sandboxing) 22 | - [Full disk encryption](full-disk-encryption) 23 | 24 | ## Inside Ubuntu Core 25 | 26 | There are many different components in an Ubuntu Core deployment that keep every system updated and secure. 27 | 28 | - [Core elements](core-elements/index) 29 | - [Stores](stores/index) 30 | - [System snaps](system-snaps/index) 31 | 32 | 33 | ```{toctree} 34 | :hidden: 35 | :titlesonly: 36 | :maxdepth: 2 37 | :glob: 38 | 39 | Community engagement 40 | How installation works 41 | Refresh control 42 | Remodelling 43 | Preseed performance 44 | Docker companion snap 45 | Full disk encryption 46 | Recovery modes 47 | Security and sandboxing 48 | Core elements 49 | Stores 50 | System snaps 51 | 52 | -------------------------------------------------------------------------------- /docs/explanation/preseed-performance.md: -------------------------------------------------------------------------------- 1 | (explanation-preseed-performance)= 2 | # Preseed performance 3 | 4 | When Ubuntu Core boots for the first time, a *seeding* process installs an initial set of snaps and runs their respective hooks. Preseeding speeds up the seeding process by performing as many of these administrative tasks as possible in advance when an image is being created. 5 | 6 | The resultant image is called a _preseeded_ image, and a preseeded image is particularly effective on devices with limited network bandwidth. 7 | 8 | With a preseeded image, the snap installation and update process is performed as part of the image creation process, before device deployment. This means a device is ready to go from the first boot, rather than requiring the further snap installation and updates that may be required with a non-preseeded image. 9 | 10 | For details on how to create a preseeded image, see [Optimise boot speed](/how-to-guides/image-creation/optimise-boot-speed). 11 | 12 | ## Measuring boot performance 13 | 14 | The time it takes for a new device to be ready can be measured with the [ubuntu_core.bootchart](/reference/kernel-boot-parameters) kernel option. When enabled, a performance profile is built for each device boot, allowing you to compare how a non-preseeded image performs against a preseeded image. 15 | 16 | The following are real examples of bootchart performance profiles, generated for the same deployment with and without preseeding and initialised over cell data. 17 | ## Without preseeding 18 | 19 | Without preseeding, a device will need to reboot after the base and system snaps have been updated, and this has a significant impact on the length of time a device takes to become available.H 20 | 21 | We can see this in our test deployment, with the generation of two bootcharts for each boot before the system becomes accessible. The total time it takes for those two boots to complete is 71.7 seconds, not including the early boot stages before bootchart starts. 22 | 23 | - [First boot](https://assets.ubuntu.com/v1/a03aa582-bootchart-20241126-0011.svg): 22.8 seconds 24 | - [Second boot](https://assets.ubuntu.com/v1/c4e63599-bootchart-20241126-0012.svg): 48.9 seconds 25 | - **Total time before the system becomes accessible: 71.7 seconds** 26 | 27 | ## With preseeding 28 | 29 | Our preseeded system did not need a reboot, and neither did it require any further updates or snap packages. This resulted in the system becoming accessible much faster, and as soon as the first boot had completed: 30 | 31 | - [First boot](https://assets.ubuntu.com/v1/84af0f6d-bootchart-20241125-2330.svg): 11.4 seconds 32 | - **Total time before the system becomes accessible: 11.4 seconds** 33 | 34 | ## Bootcharts 35 | 36 | All three bootchart excerpts below show: 37 | 38 | - **ping** read from storage utilisation 39 | - **red** write to storage utilisation 40 | - **blue** CPU utilisation 41 | - **yellow** CPU wait time 42 | 43 | ### Without preseeding 44 | 45 | The following shows two separate boots, the first for **22.8 seconds** and the second lasting **48.9 seconds**. 46 | 47 | ![No preseed Ubuntu Core bootchart](https://assets.ubuntu.com/v1/d632505b-no-preseed-bootchart.png) 48 | 49 | ### With preseeding 50 | 51 | The following shows the only boot required for a preseeded image, lasting **11.4 seconds**. 52 | 53 | ![Preseeded Ubuntu Core bootchart](https://assets.ubuntu.com/v1/35aabcc9-preseed-bootchart.png) 54 | 55 | -------------------------------------------------------------------------------- /docs/explanation/recovery-modes.md: -------------------------------------------------------------------------------- 1 | (explanation-recovery-modes)= 2 | # Recovery modes 3 | 4 | The following recovery functions are currently available: 5 | 6 | * **[Install mode / factory mode](#install-mode)**: initialise the device from an onboard system image 7 | * **[Run mode](#run-mode)**: restarts normally and runs the boot process 8 | * **[Recover mode](#recover-mode)**: reboot into recovery mode for data retrieval 9 | * **[Factory reset](#factory-reset)**: erase system data and initialise the device to its factory state 10 | 11 | See [Using recovery modes](/how-to-guides/manage-ubuntu-core/use-a-recovery-mode) for details on how these modes are accessed. 12 | 13 | ## Install mode 14 | 15 | With **install mode**, all existing user and system data on the device will be removed and the device will be initialised from the system version image dated and listed in the reinstall text. 16 | 17 | Unlike with a factory reset (see below), install mode will erase the contents of the [ubuntu-save](/explanation/core-elements/storage-layout) partition, reverting the device to its manufactured state, potentially removing configuration data essential to its functionality. 18 | 19 | After the re-initialisation process has completed, you will need to step through the installation process of network configuration and account credentials again. 20 | 21 | See [Installation steps](/tutorials/try-pre-built-images/install-on-a-device/use-raspberry-pi-imager) for further details on how the installation will proceed. 22 | 23 | ```{admonition} Re-installation failure 24 | :class: caution 25 | 26 | Re-installation can fail if a device's TPM is assigned to a previous installation. To solve this issue, reset or clear the TPM assignment from the device's BIOS before selecting reinstall as a recovery mode. 27 | ``` 28 | 29 | ## Run mode 30 | 31 | When booting in **run mode**, the device will attempt to boot normally, with no further option to recover or reinstall the system unless the recovery process is reinstantiated. 32 | 33 | ## Recover mode 34 | 35 | In **recovery mode**, the device operates as it would from a pristine initial installation, including its snaps, via a temporary file system. 36 | 37 | Most importantly, however, the running system data is untouched. This allows you to log in to the system using prior credentials to recover your data, either via SSH or locally after setting up a password for the user. 38 | 39 | Rebooting from recovery mode will return the system to run mode. 40 | 41 | ## Factory reset 42 | 43 | The **factory reset** option will erase all system data and reset the device to its original _fresh from the factory_ state. This means that not everything is removed. 44 | 45 | In particular, the contents of the [ubuntu-save](/explanation/core-elements/storage-layout) partition remains intact. This partition typically contains configuration data essential for the original functionality of the device, such as network configuration details. To fully initialise such a device, and remove all data, use `install mode`. 46 | 47 | This is a dangerous option and should only be performed when you are certain the data on a device data is either backed-up or unwanted. 48 | 49 | Additionally, the [install-device hook](/explanation/how-installation-works.md#the-install-device-hook) may optionally be executed with a factory-reset. 50 | -------------------------------------------------------------------------------- /docs/explanation/stores/brand-accounts.md: -------------------------------------------------------------------------------- 1 | (explanation-stores-brand-accounts)= 2 | # Brand accounts 3 | 4 | The global [Snap Store](https://snapcraft.io/store) is the default source for all snaps, including those used by Ubuntu Core. It’s where the majority of snaps are published, where public, unlisted and private snaps can be shared with users and collaborators, and where developers can manage their releases across channels and tracks. 5 | 6 | But snaps can also be hosted, and published from a dedicated snap store, often called a [Brand store](/explanation/stores/dedicated-snap-stores) or IoT App Store. For a more in-depth look at dedicated snap stores, and how they're used with Ubuntu Core and IoT devices, see the [IoT App Store](https://ubuntu.com/core/services/guide/iot-app-store-intro) documentation. 7 | 8 | A store is managed and governed through a brand account and the authority it delegates to other associated accounts. This is outlined below. 9 | 10 | ## Brand accounts 11 | 12 | A brand account is an ordinary Ubuntu SSO account augmented by the store team after a support request. It then defines the scope of authority of a dedicated snap store, and it must be used for certain functions. 13 | 14 | Accounts are registered the same as any other account, and it’s recommended a brand account acts as an umbrella account by using the project name or the legal entity responsible for the device. 15 | 16 | The brand account can be used to: 17 | 18 | * Generate, register, and hold the sign keys for the brand infrastructure. 19 | * Sign Model Assertions used to build images that point at a dedicated snap store. 20 | * Register kernel and gadget snap names. 21 | 22 | The kernel and gadget snaps are special snaps that can only be registered by the brand account, which also must also be given a publisher role in the base store. Similarly, kernel and gadget snap names must be registered by the brand account (or by Canonical). See [Snaps in Ubuntu Core](/explanation/core-elements/snaps-in-ubuntu-core) for more details on the snaps used to build Ubuntu Core. 23 | 24 | Use of the Brand Account and its credentials should be strictly limited. Canonical recommends that the Brand Account not be assigned any Roles that are not strictly needed. Do not make the Brand Account a store Administrator, a Reviewer or a Viewer. 25 | 26 | When the Brand Account generates keys, they are only stored locally in ( ~/.snap/gnupg). These keys must be kept safe. 27 | 28 | ```{admonition} Enable two-factor authentication 29 | :class: caution 30 | We recommend enabling two-factor authentication on all Ubuntu SSO accounts, but especially the brand and administrator accounts described below. See [SSO two-factor authentication](https://help.ubuntu.com/community/SSO/2FactorAuthentication) for details. 31 | ``` 32 | 33 | ## Roles 34 | 35 | Roles are a vital part of the device and snap management lifecycle. They enable accounts other than the master brand account to control various aspects of the deployment process, and for those aspects to be safeguarded from the key and registry functions that maintain the integrity of the brand account. 36 | 37 | As with the brand account, roles are assigned to a regular Ubuntu SSO account by a project administrator via [ https://snapcraft.io/admin]( https://snapcraft.io/admin): 38 | 39 | ![Ubuntu Core brand account add new member](https://assets.ubuntu.com/v1/a2ea6a4d-core-store.png) 40 | 41 | The following roles can be selected: 42 | - **Admin** 43 | The administrator role in the App Store has the highest level of permissions granted. Administrator permissions include the abilities to: 44 | - **Reviewer** 45 | Reviewers approve software changes made to snaps before they can be published to the Store, if the administrator has enabled the requirement for reviews in the Store. 46 | - **Viewer** 47 | The viewer role in the App Store has the fewest permissions granted. Viewers can see and download snaps from their IoT App Store. Downloaded snaps can be used to build images or perform testing. 48 | - **Publisher** 49 | The publisher role in the App Store is linked to publishing snaps to the Store, including registering snap names, uploading releases and specific revisions and configuring team collaborators. 50 | 51 | See [Setting up account roles](https://ubuntu.com/core/services/guide/setting-up-account-roles) for more details on how roles are created and what they can do, and take a look at our [IoT App Store](https://ubuntu.com/core/services/guide/iot-app-store-intro) documentation for a more comprehensive look at dedicated snap stores. 52 | 53 | -------------------------------------------------------------------------------- /docs/explanation/stores/index.md: -------------------------------------------------------------------------------- 1 | # Stores 2 | 3 | A store hosts and provides both the snap packages themselves and signed assertions required to securely maintain and update an Ubuntu Core device. 4 | 5 | ## Running a store 6 | 7 | Applications and updates are delivered from a _store_. By default, this is Canonical’s Snap Store, but it can also be a dedicated snap store of your own, controlled through a _brand account_. 8 | 9 | - [Store overview](store-overview) 10 | - [Brand accounts](brand-accounts) 11 | - [Dedicated snap stores](dedicated-snap-store) 12 | - [Store scoping](store-scoping) 13 | 14 | 15 | ```{toctree} 16 | :hidden: 17 | :titlesonly: 18 | :maxdepth: 2 19 | :glob: 20 | 21 | Store overview 22 | Brand accounts 23 | Dedicated snap store 24 | Store scoping 25 | -------------------------------------------------------------------------------- /docs/explanation/stores/store-overview.md: -------------------------------------------------------------------------------- 1 | (explanation-stores-store-overview)= 2 | # Store overview 3 | 4 | Ubuntu Core includes access to the Canonical's [Snap Store](https://snapcraft.io/store) by default. This allows any developer to easily release and support apps for multiple architectures, on multiple release channels, from daily builds to stable releases. 5 | 6 | See [Releasing to the Snap Store](https://snapcraft.io/docs/releasing-to-the-snap-store) for more details on how to publish and distribute snaps to devices from the Snap Store. 7 | 8 | ## Dedicated Snap Stores 9 | 10 | For larger projects and ISVs, it is often a requirement to publish snaps using a brand account to a brand-specific dedicated Snap Store. 11 | 12 | A [Dedicated Snap Store](/explanation/stores/dedicated-snap-stores) allows vendors running Ubuntu Core and snap-based devices to control exactly what snaps are available, and when. It can inherit selected packages from other snap stores, and host a set of snaps specific to a brand and device models, and be either open to all developers or a specific list. 13 | 14 | Here is an overview of how to create a brand account and define collaborators. 15 | 16 | ## Registering accounts 17 | 18 | To create an account, go to . We then recommend the following process: 19 | 20 | - create an umbrella/brand account using the project name or name of the legal entity publishing the software 21 | - let each team member who releases and manages snaps register a personal account 22 | - grant each team member access to the snaps by adding their personal accounts as collaborators 23 | 24 | ## Registering Snaps 25 | 26 | Snaps can be registered using the `snapcraft` tool or via the web. Snaps should be registered using the brand/umbrella account. 27 | 28 | ### Registering snaps with Snapcraft 29 | 30 | - install `snapcraft` using `snap install snapcraft --classic` on Linux or `brew install snapcraft` on macOS 31 | - execute `snapcraft login` and authenticate using the brand/umbrella account 32 | - once authenticated register the snap name(s) with `snapcraft register yoursnapname` 33 | 34 | For more details on this process, see [Registering your app name](https://snapcraft.io/docs/registering-your-app-name). 35 | 36 | ### Registering snaps via the web 37 | 38 | - login to [https://snapcraft.io](https://snapcraft.io/) using the brand/umbrella account 39 | - register snap(s) here: [https://snapcraft.io/account/register-name]() 40 | 41 | ## Collaborators 42 | 43 | When you've registered snap(s) using a brand/umbrella account, you should add team members' personal accounts to the umbrella/brand account via the Dashboard for your snap. For example: 44 | 45 | https://dashboard.snapcraft.io/snaps/yoursnapname/collaboration/ 46 | 47 | Collaborators can then push and release snaps using their personal accounts. 48 | 49 | -------------------------------------------------------------------------------- /docs/explanation/stores/store-scoping.md: -------------------------------------------------------------------------------- 1 | (explanation-stores-store-scoping)= 2 | # Store scoping 3 | 4 | _Store scoping_ is the inclusion of a [dedicated snap store](dedicated-snap-store) _`on-store`_ constraint linked to an [auto-connection](https://snapcraft.io/docs/auto-connection-mechanism) in the [snap-declaration assertion](/reference/assertions/snap-declaration), a file used to describe various snap properties. 5 | 6 | Linking an auto-connection grant to a dedicated snap store limits the scope of an interface. This then safeguards against malicious attacks that might otherwise allow auto-connections to be made outside a dedicated snap store when a snap is installed on a generic device. 7 | ## Declaration syntax 8 | 9 | Old versions of the snap-declaration assertion could only define auto-connections in a way that couldn't link connections to a dedicated snap store: 10 | 11 | ```yaml 12 | type: snap-declaration 13 | format: 1 14 | authority-id: canonical 15 | revision: 1 16 | series: 16 17 | snap-id: some-snap-id 18 | plugs: 19 | snapd-control: 20 | allow-auto-connection: true 21 | allow-installation: true 22 | publisher-id: some-account-id 23 | snap-name: snap-name 24 | timestamp: 2022-01-26T11:15:49.885580Z 25 | sign-key-sha3-384: some-account-key 26 | ``` 27 | 28 | With the release of [snapd](https://snapcraft.io/docs/glossary#heading--snapd) version _2.36_ in 2018, the snap-declaration assertion was updated to include a [dedicated snap store](dedicated-snap-store) definition for each granted interface: 29 | 30 | ```yaml 31 | type: snap-declaration 32 | format: 1 33 | authority-id: canonical 34 | revision: 2 35 | series: 16 36 | snap-id: some-snap-id 37 | plugs: 38 | snapd-control: 39 | allow-auto-connection: 40 | on-store: 41 | - your-dedicated-snap-store 42 | allow-installation: 43 | on-store: 44 | - your-dedicated-snap-store 45 | publisher-id: some-account-id 46 | snap-name: snap-name 47 | timestamp: 2022-01-26T11:15:49.885580Z 48 | sign-key-sha3-384: some-account-key 49 | ``` 50 | 51 | The following shows the previous snap-declaration assertion updated to use the new dedicated snap store limits with _your-dedicated-snap-store_ as an example: 52 | 53 | ```yaml 54 | Old version New version 55 | 56 | plugs: plugs: 57 | snapd-control: snapd-control: 58 | allow-auto-connection: true allow-auto-connection: 59 | allow-installation: true on-store: 60 | - your-dedicated-snap-store 61 | allow-installation: 62 | on-store: 63 | - your-dedicated-snap-store 64 | ``` 65 | 66 | Design limitations mean a snap can't be prevented from being installed, but linking an auto-connection to a dedicated snap store means any auto-connection can be prevented from happening. 67 | 68 | The [Snap Store team](https://snapcraft.io/docs/permission-requests) admins can enable this feature with no action needed from the customer: the process includes generating new revisions for each snap-declaration assertion, for each snap, with special interface grants in the customer's dedicated snap store. 69 | 70 | ## Devices on shelves 71 | 72 | The oldest version of snapd that supports snap-declaration store scoping is _2.36_. 73 | 74 | If a customer has devices already flashed and sitting on shelves with a snapd version _2.36_ or newer, the addition of store scoping will be transparent to those devices when first booted. 75 | 76 | If a customer has devices on shelves flashed with a version of snapd _older_ than 2.36, they should also update autonomously, with snapd updating first before migrating the assertions to the newer formats. This assumes refreshing is correctly in place. 77 | 78 | Lastly, if a customer has **existing** snaps that require **new** auto-connections in newer revisions, they should consider defining the [assumes attribute](https://snapcraft.io/docs/snapcraft-top-level-metadata#heading--assumes) in their snapcraft.yaml file. 79 | 80 | Pre-existing auto-connections in a pre store-scoped snap-declaration should not be affected because of the assertion format handling. 81 | 82 | ## Rolling back store scoping 83 | 84 | In the unlikely event that enabling store scoping causes a customer to experience issues, the constraint can be disabled. It's possible for a snap to have a snap-declaration assertion revision with the `on-store` constraint and next one without, for example, and snapd will use the newer revision. 85 | 86 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/bluetooth/bluetooth-snaps.md: -------------------------------------------------------------------------------- 1 | # Add Bluetooth to snaps 2 | 3 | This section will show what are the necessary bits in the *snapcraft.yaml* while snapping an application that uses Bluetooth. 4 | 5 | ## Bluetooth Interfaces 6 | 7 | There are two Bluetooth related interfaces available on Ubuntu Core: 8 | 9 | - [bluez](https://snapcraft.io/docs/bluez-interface): allows accessing the Bluetooth service through D-Bus API 10 | - [bluetooth-control](https://snapcraft.io/docs/bluetooth-control-interface): used to talk to the kernel-side of the Bluetooth stack directly. 11 | 12 | ## Contents of snapcraft.yaml 13 | 14 | This section presents a *snapcraft.yaml* template for applications that use Bluetooth. 15 | 16 | The *bluez* snap discussed previously is a somewhat complex thing because it includes both the Bluetooth service ( *bluetoothd* and *obexd* ) and the client applications ( *bluetoothctl* and *obexctl* ). Because of this it defines the slots and plugs. 17 | 18 | The standalone Bluetooth application that could be used in place of *bluetoothctl* needs to take care only of the client side. In fact all it has to do is to define a *bluez* plug. 19 | 20 | In the example below the *foo* application defines a *client* plug that is nothing more than a plug side of the *bluez* interface. 21 | ``` 22 | plugs: 23 | client: 24 | interface: bluez 25 | 26 | apps: 27 | foo: 28 | command: "bin/foo-command" 29 | plugs: [client] 30 | 31 | ``` 32 | Note that if by any chance your application needs to talk directly to the chip, then the *bluetooth-control* interface will suit these needs better than the *bluez* one. 33 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/index.md: -------------------------------------------------------------------------------- 1 | # System snaps 2 | 3 | System snaps provide additional device functionality, usually associated with connectivity. They're managed and maintained by separate projects outside of the central Ubuntu Core. 4 | 5 | ## Connectivity options 6 | 7 | There are several system snaps that can be used to connect to a local or wide area network, as well as local devices over Bluetooth. 8 | 9 | - [Bluetooth manager](bluetooth/index) 10 | - [Modem Manager](modem-manager/index) 11 | - [Network Manager](network-manager/index) 12 | 13 | ```{toctree} 14 | :hidden: 15 | :titlesonly: 16 | :maxdepth: 2 17 | :glob: 18 | 19 | Bluetooth manager 20 | Modem Manager 21 | Network Manager 22 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/1: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/013a48aadd2476a1f8c4d448da43b8ed8b05639c/docs/explanation/system-snaps/modem-manager/1 -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/debug.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-modem-manager-reference-debug)= 2 | # Debug 3 | 4 | 5 | The debug configuration option controls the amount of logs produced by the modem-manager snap. It is useful for collecting information required to either report a bug or investigate a modem-manager failure. 6 | 7 | It is disabled by default and has to be explicitly turned on for usage. 8 | 9 | Note that the debug logs may contain sensitive information. 10 | 11 | ## Enable Debug 12 | 13 | The modem-manager snap provides a single configuration option which can be used to turn the debug feature either on or off: 14 | 15 | * **debug.enable** 16 | 17 | The option takes a boolean value. The meaning of the possible values are: 18 | 19 | * **true:** Enable logging debug information 20 | * **false (default):** Disable logging debug information 21 | 22 | Changing the **debug** configuration option has immediate effect and also affects future executions of the MM daemon. 23 | 24 | **Example:** Enable debug feature 25 | ```bash 26 | $ snap set modem-manager debug.enable=true 27 | ``` 28 | **Example:** Disable debug feature. 29 | ```bash 30 | $ snap set modem-manager debug.enable=false 31 | ``` 32 | ## Viewing logs 33 | 34 | The debug information, when enabled, will be available in the journal and can be viewed with: 35 | ```bash 36 | $ journalctl --no-pager -u snap.modem-manager.modemmanager.service 37 | ``` 38 | 39 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-modem-manager-index)= 2 | # Modem Manager 3 | 4 | The modem-manager snap is based on [upstream ModemManager](https://www.freedesktop.org/wiki/Software/ModemManager/), which is a D-Bus-activated daemon which controls mobile broadband (2G/3G/4G) devices and connections. ModemManager is able to prepare and configure a wide variety of modems and setup connections with them. 5 | 6 | The modem-manager snap should be used in most cases jointly with the [network-manager](/explanation/system-snaps/network-manager/index) snap. NetworkManager can be used to set cellular connection settings and to start and stop the connection. 7 | 8 | The recommended way of using a modem in [Ubuntu Core](/index) is described in [NetworkManager documentation](../network-manager/index). This documentation serves as further reference in case more control on the cellular modem is needed. It is important to note that many of the things explained are automatically performed when using NetworkManager. 9 | 10 | ## What ModemManager Offers 11 | 12 | The main features provided by ModemManager are: 13 | 14 | * Cellular connectivity for a [wide variety of modems](https://www.freedesktop.org/wiki/Software/ModemManager/SupportedDevices/) 15 | * Support for AT commands, QMI, and MBIM interfaces 16 | * SMS messages support for USB modems 17 | 18 | ## Upstream documentation 19 | 20 | Existing documentation from the upstream project can be found [here](https://www.freedesktop.org/wiki/Software/ModemManager/). 21 | 22 | ```{toctree} 23 | :hidden: 24 | :titlesonly: 25 | :maxdepth: 2 26 | :glob: 27 | 28 | Install Modem Manager 29 | Using Modem Manager 30 | Debug Modem Manager 31 | Release notes 32 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/install-modem-manager.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-modem-manager-install-modem-manager)= 2 | # Install Modem Manager 3 | 4 | The ModemManager snap is currently available from the Ubuntu Store. It can be installed on any system that supports snaps but is only recommended on [Ubuntu Core](/index) at the moment. 5 | 6 | You can install the snap with the following command: 7 | ```bash 8 | snap install modem-manager modem-manager (1.10/stable) 1.10.0-4 from Canonical✓ installed 9 | ``` 10 | 11 | All necessary plugs and slots will be automatically connected within the installation process. You can verify this with: 12 | ```bash 13 | snap connections modem-manager Interface Plug Slot Notes modem-manager modem-manager:mmcli modem-manager:service - modem-manager network-manager:modem-manager modem-manager:service - 14 | ``` 15 | We see here that the *mmcli* command line utility can use the ModemManager service and that network-manager can do the same (we will see that if the network-manager snap is already installed in the system). 16 | 17 | Once the installation has successfully finished the ModemManager service is running in the background. You can check its current status with 18 | ```bash 19 | $ systemctl status snap.modem-manager.modemmanager.service 20 | ● snap.modem-manager.modemmanager.service - Service for snap application modem-manager.modemmanager Loaded: loaded (/etc/systemd/system/snap.modem-manager.modemmanager.service; enabled; vendor preset: enabled) 21 | Active: active (running) since Fri 2020-07-10 08:34:43 UTC; 2min 20s ago Main PID: 2047 (ModemManager) 22 | Tasks: 3 (limit: 569) 23 | CGroup: /system.slice/snap.modem-manager.modemmanager.service └─2047 /snap/modem-manager/414/usr/sbin/ModemManager --filter-policy=STRICT --log-level=INFO 24 | ``` 25 | Now you have ModemManager successfully installed. In the next sections we will briefly explain how to use part of ModemManager's features, using *mmcli* command line interface to interact with the service. For a complete reference on what can be done with ModemManager, take a look at [ *mmcli* man page](https://www.freedesktop.org/software/ModemManager/man/latest/mmcli.8.html) and to [ModemManager's D-Bus interface](https://www.freedesktop.org/software/ModemManager/api/latest/). It is also possible to use *dbus-send* to directly access the D-Bus interface if desired. 26 | 27 | Finally, note that to run both *mmcli* and *dbus-send* we need root permissions, so we use *sudo* with them. 28 | 29 | ## Tracks and channels 30 | 31 | The modem-manager snap has currently five tracks, and with the exception of the 'latest' and '1.10' track, the track will refer to the version of the base used. 32 | 33 | * **24** : Contains upstream version 1.23.4 and has a core24 base. 34 | * **22** : Contains upstream version 1.20.0 and has a core22 base. Nowadays, this is the one installed by default if the channel is not specified when running `snap install`. 35 | * **20** : Contains upstream version 1.18.6 and has a core20 base. 36 | * **1.10** : Contains upstream version 1.10.0 and has a core18 base. The track name refers to the upstream version. More modern releases have changed the convention so the track now refers to the base snap. 37 | * **latest** : Contains upstream version 1.8.0 and has a core16 base. Despite the unfortunate name (there are historical reasons for that) it is the oldest version. 38 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/release-notes.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-modem-manager-reference-release-notes)= 2 | # Release Notes 3 | 4 | 5 | The version numbers mentioned on this page correspond to those released in the Ubuntu snap store. 6 | 7 | You can check with the following command which version you have currently installed: 8 | ```bash 9 | $ snap info modem-manager name: modem-manager summary: ModemManager is a service which controls mobile broadband publisher: Canonical✓ store-url: https://snapcraft.io/modem-manager contact: snaps@canonical.com license: unset description: | ModemManager is a D-Bus-activated daemon which controls mobile broadband (2G/3G/4G) devices and connections. Whether built-in devices, USB dongles, bluetooth-paired telephones or professional RS232/USB devices with external power supplies, ModemManager is able to prepare and configure the modems and setup connections with them. The modem-manager snap is usually used together with the network-manager snap. The snap is geared towards devices and IoT and is optimized for Ubuntu Core. Its usage on desktop/server Ubuntu is possible, but manual connection of interfaces is needed and do not expect full integration with the GUI. Documentation on how to use the snap can be found in https://docs.ubuntu.com/core/en/stacks/network/modem-manager/docs/. Please find the source code at https://code.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager commands: - modem-manager.mbim-network - modem-manager.mbimcli - modem-manager.mmcli - modem-manager.qmi-network - modem-manager.qmicli services: modem-manager.modemmanager: simple, enabled, active snap-id: KtwxgRlwCAVKFw92BUdt1WloH1Va3QPo tracking: 1.10/stable refresh-date: today at 08:34 UTC channels: 1.10/stable: 1.10.0-4 2020-01-21 (414) 1MB - 1.10/candidate: 1.10.0-4 2020-01-21 (414) 1MB - 1.10/beta: 1.10.0-4 2020-01-20 (414) 1MB - 1.10/edge: 1.10.0-5-dev 2020-02-11 (438) 1MB - latest/stable: 1.8.0-12 2020-02-04 (426) 1MB - latest/candidate: 1.8.0-12 2020-02-04 (426) 1MB - latest/beta: 1.8.0-12 2020-01-21 (426) 1MB - latest/edge: 1.8.0-12 2020-02-04 (426) 1MB - 20/stable: – 20/candidate: – 20/beta: 1.12.8-1 2020-06-22 (454) 1MB - 20/edge: 1.12.8-1-dev 2020-06-22 (451) 1MB - installed: 1.10.0-4 (414) 1MB - 10 | ``` 11 | The detailed changelog for each version can be consulted in the sources for each track: 12 | 13 | * For track 20, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog?h=snap-20) 14 | * For track 1.10, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog?h=snap-1.10) 15 | * For track latest (note again this is not actually the more modern MM), [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/modem-manager/tree/ChangeLog) 16 | 17 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/using-modem-manager.md: -------------------------------------------------------------------------------- 1 | # Using Modem Manager 2 | 3 | If we have a modem in the system, we should be able to see it with _mmcli -L_, for instance: 4 | 5 | ```bash 6 | $ sudo mmcli -L 7 | Found 1 modems: 8 | /org/freedesktop/ModemManager1/Modem/0 [BRAND] MODEL 9 | ``` 10 | The command shows the D-Bus path for the modem, with the number at the end of the path being the argument to access it from the cli: 11 | 12 | ```bash 13 | $ sudo mmcli -m 0 14 | 15 | /org/freedesktop/ModemManager1/Modem/0 (device id '817f7e2b3c6dfdf1d4ee7f4c4ecc34de61bc5de9') 16 | ``` 17 | ## Available commands 18 | 19 | The ModemManager upstream project comes with a few commands which can be used to control and manage the ModemManager service. This page gives a short overview of those commands which are available as part of the snap and what they are used for. Further details about their usage is given on linked pages. 20 | 21 | ### mmcli 22 | 23 | The **mmcli** command offers a command-line based way to control and manage the ModemManager service. 24 | 25 | An explanatory description of the command and available options is available [here](https://www.freedesktop.org/software/ModemManager/man/latest/mmcli.8.html) 26 | 27 | ### modem-manager.mbimcli 28 | 29 | **mbimcli** can be used to control directly devices that use the MBIM protocol. 30 | 31 | More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/mbimcli.1.html). 32 | 33 | ### modem-manager.qmicli 34 | 35 | **qmicli** can be used to control directly devices that use the QMI protocol. 36 | 37 | More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/qmicli.1.html). 38 | 39 | ### modem-manager.mbim-network 40 | 41 | **mbim-network** can be used to start a cellular connection for devices that support the MBIM protocol, mainly for debugging purposes. 42 | 43 | More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/mbim-network.1.html). 44 | 45 | ### modem-manager.qmi-network 46 | 47 | **qmi-network** can be used to start a cellular connection for devices that support the QMI protocol, mainly for debugging purposes. 48 | 49 | More details can be found in the [man page](http://manpages.ubuntu.com/manpages/focal/man1/qmi-network.1.html). 50 | 51 | 52 | ## Enter SIM passwords 53 | 54 | We can find out if the SIM is locked by issuing: 55 | 56 | ```bash 57 | sudo mmcli -m 0 58 | ``` 59 | 60 | ## Configure cellular connections 61 | 62 | To establish a cellular connection: 63 | 64 | ```bash 65 | $ sudo mmcli -m 0 --simple-connect="apn=my.carrier.apn" 66 | successfully connected the modem 67 | ``` 68 | 69 | NOTE: This makes the modem establish a cellular connection but does not create a network interface, so the connection is not directly usable. To be able to use data, pppd or {mbim,qmi}-proxy need to be run with the right parameters. It is highly recommended to use NetworkManager instead, as explained in the 'About' section. 70 | 71 | To find out the bearer path: 72 | ```bash 73 | $ sudo mmcli -m 0 --list-bearers 74 | Found 1 bearers: 75 | /org/freedesktop/ModemManager1/Bearer/0 76 | ``` 77 | To retrieve information about the bearer (as usual, we specify the bearer with the number at the end of the bearer's D-Bus path): 78 | 79 | ```bash 80 | $ sudo mmcli -b 0 81 | Bearer '/org/freedesktop/ModemManager1/Bearer/0' 82 | ``` 83 | 84 | ## D-Bus API 85 | 86 | Documentation for the D-Bus API is provided by the ModemManager upstream project [here](https://www.freedesktop.org/software/ModemManager/api/latest/). 87 | 88 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-cellular-connections.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-configure-cellular-connections)= 2 | # Configure cellular connections 3 | 4 | For cellular connections, first install the modem-manager snap with: 5 | ```bash 6 | snap install modem-manager 7 | ``` 8 | Check whether a modem was properly detected via: 9 | 10 | ```bash 11 | $ sudo modem-manager.mmcli -L 12 | Found 1 modems: 13 | /org/freedesktop/ModemManager1/Modem/0 [description] 14 | ``` 15 | In this case we have just one modem, with index 0 (the number at the end of the D-Bus object path). 16 | 17 | Show detailed information about the modem using that index: 18 | ```bash 19 | $ sudo modem-manager.mmcli -m 0 20 | /org/freedesktop/ModemManager1/Modem/0 (device id '871faa978a12ccb25b9fa30d15667571ab38ed88') 21 | ``` 22 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-shared-connections.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-configure-shared-connections)= 2 | # Configure shared connections 3 | 4 | 5 | NetworkManager makes very easy to share connectivity, using the device as a gateway to which other devices can connect. That requires running commands similar to 6 | ```bash 7 | nmcli c add con-name type ethernet ifname ipv4.method shared ipv6.method ignore 8 | nmcli c up 9 | ``` 10 | where `` is an arbitrary name we give to the connection and `` is the name of the interface where external devices will connect to. In this case we are using an ethernet interface ( `type ethernet` ) and we provide IPv4 addresses, but this extends to other interfaces and to IPv6. 11 | 12 | When the connection is up, NM starts a DHCP server listening on `` and changes the networking configuration so we can forward packages and masquerading is enabled for the interface. Of course, for this to work we need an interface different from `` that has to have external connectivity. 13 | 14 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-the-snap/connectivity-check.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-snap-configuration-connectivity-check)= 2 | # Connectivity check 3 | 4 | Connectivity checking is a NetworkManager functionality that allows periodically testing whether the system can actually access the internet or not. The network-manager snap allows configuring this feature by using the following snap settings: 5 | 6 | * **connectivity.interval** : it specifies the number of seconds between checks. If set to 0, it disables connectivity check. Set to 300 by default. 7 | * **connectivity.response** : This is the expected HTTP body response from the server specified by connectivity.uri. 8 | * **connectivity.uri** : The URI where NM is going to periodically access to check connectivity. 9 | 10 | More details on how these options work can be found in the connectivity section of the [NetworkManager.conf configuration file documentation](https://developer.gnome.org/NetworkManager/stable/NetworkManager.conf.html). 11 | 12 | Some example commands on how to set a check every three minutes using the Ubuntu connectivity check server are 13 | ```bash 14 | snap set network-manager connectivity.uri=http://connectivity-check.ubuntu.com/ $ snap set network-manager connectivity.interval=180 15 | ``` 16 | 17 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-the-snap/debug.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-snap-configuration-debug)= 2 | # Debug the snap 3 | 4 | Debug is a feature that controls the amount of logs produced by the network-manager snap. It is useful for collecting information required to either report a bug or investigate a network-manager failure (if happens). 5 | 6 | It is disabled by default and has to be explicitly turned on for usage. 7 | 8 | Note that the debug logs may contain sensitive information. 9 | 10 | ## Enable Debug 11 | 12 | The network-manager snap provides a single configuration option which can be used to turn the debug feature either on or off: 13 | 14 | * **debug.enable** 15 | 16 | The option takes a boolean value. The meaning of the possible values are: 17 | 18 | * **true:** Enable logging debug information 19 | * **false (default):** Disable logging debug information 20 | 21 | Changing the **debug** configuration option has immediate effect and also affects future executions of the NM daemon. 22 | 23 | **Example:** Enable debug feature 24 | ```bash 25 | snap set network-manager debug.enable=true 26 | ``` 27 | **Example:** Disable debug feature. 28 | ```bash 29 | snap set network-manager debug.enable=false 30 | ``` 31 | ## Viewing logs 32 | 33 | The debug information, when enabled, will be available in the journal and can be viewed with: 34 | ```bash 35 | journalctl --no-pager -l -u snap.network-manager.networkmanager.service 36 | ``` 37 | 38 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-the-snap/default-renderer.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-snap-configuration-default-renderer)= 2 | # Default renderer 3 | 4 | 5 | The NetworkManager snap provides a configuration option, `defaultrenderer` , to adjust if it should be the default network renderer or not. By default, it is set to `true` . To change it: 6 | 7 | ```bash 8 | $ snap set network-manager defaultrenderer=false 9 | ``` 10 | 11 | For the core16 snap, there is an option called `ethernet.enable` that does basically the same. See the [NetworkManager and netplan](/explanation/system-snaps/network-manager/how-to-guides/networkmanager-and-netplan) section for more details. 12 | 13 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-the-snap/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-snap-configuration-index)= 2 | # Configure the snap 3 | 4 | The Network Manager snap includes its own configuration options, separate from those of Network Manager itself. 5 | 6 | Documentation of the D-Bus API is provided by the [NetworkManager upstream](https://networkmanager.dev/docs/api/latest/) project. 7 | 8 | ## Configuration options 9 | 10 | - [Check connectivity](connectivity-check.md) 11 | - [Debug the snap](debug.md) 12 | - [Default renderer](default-renderer.md) 13 | - [Wake on WLAN](wake-on-wlan.md) 14 | - [Wi-Fi powersave](wifi-powersave.md) 15 | 16 | 17 | ```{toctree} 18 | :hidden: 19 | :titlesonly: 20 | :maxdepth: 2 21 | :glob: 22 | 23 | * 24 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-the-snap/wifi-powersave.md: -------------------------------------------------------------------------------- 1 | # Wi-Fi powersave 2 | 3 | Wi-Fi Powersave is a feature that allows a device to suspend its radio activity after a fixed period of inactivity. The device remains idle for a fixed time, usually about 100ms, and once it is reached it wakes up to check if the infrastructure has any packets queued up for it. 4 | 5 | The NetworkManager snap allows to configure this option by either enabling or disabling the powersave feature. 6 | 7 | You can read more about the Wi-Fi Powersave feature on the following sites: 8 | 9 | * https://wireless.wiki.kernel.org/en/developers/documentation/ieee80211/power-savings 10 | 11 | ## Enable Wi-Fi Powersave 12 | 13 | To allow users to enable or disable Wi-Fi Powersave, the snap provides a single configuration option: 14 | 15 | * wifi.powersave 16 | 17 | Option can be set via the configuration API snaps provide. See [Managing snap configuration](https://snapcraft.io/docs/configuration-in-snaps) for more details. 18 | 19 | ### wifi.powersave 20 | 21 | This configuration option accepts the following values: 22 | 23 | * **disabled (default):** Wi-Fi powersaving is disabled 24 | * **enabled:** Wi-Fi powersaving is enabled 25 | 26 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-vpn-connections.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-configure-vpn-connections)= 2 | # Configure VPN connections 3 | 4 | VPN support requires both the use of `core22` and network-manager from a `22/*` channel. Currently, two types of VPN are supported: 5 | 6 | - [OpenVPN](#openvpn) 7 | - [WireGuard](#wireguard) 8 | 9 | ## OpenVPN 10 | 11 | Network Manager supports two methods to create an OpenVPN connection: 12 | - import an OpenVPN credentials file 13 | - set required parameters manually with `nmcli` invocations 14 | 15 | In both cases, files used in the definition must be copied to folders where the _network-manager_ snap has access, which is usually in SNAP_DATA or SNAP_COMMON folders. 16 | 17 | The first method requires only that the OpenVPN configuration file is copied to one of these locations: 18 | 19 | ```bash 20 | sudo nmcli c import type openvpn file /var/snap/network-manager/common/myopenvp.ovpn 21 | ``` 22 | 23 | This command needs to be run as root because it creates certificate and key files with data extracted from the configuration file. These need to be accessible by the network-manager snap, which itself runs with root id. 24 | 25 | Using the second method requires copying around certificates and keys and creating/modifying the connection as required. For instance: 26 | 27 | ```bash 28 | nmcli c add connection.id vpntest connection.type vpn \ 29 | vpn.service-type org.freedesktop.NetworkManager.openvpn \ 30 | ipv4.never-default true \ 31 | ipv6.never-default true \ 32 | +vpn.data ca=/var/snap/network-manager/common/creds/server_ca.crt \ 33 | +vpn.data cert=/var/snap/network-manager/common/creds/user.crt \ 34 | +vpn.data cert-pass-flags=0 \ 35 | +vpn.data cipher=AES-128-CBC \ 36 | +vpn.data comp-lzo=adaptive \ 37 | +vpn.data connection-type=tls \ 38 | +vpn.data dev=tun \ 39 | +vpn.data key=/var/snap/network-manager/common/creds/user.key \ 40 | +vpn.data ping=10 \ 41 | +vpn.data ping-restart=60 \ 42 | +vpn.data remote=: \ 43 | +vpn.data remote-cert-tls=server \ 44 | +vpn.data ta=/var/snap/network-manager/common/creds/tls_auth.key \ 45 | +vpn.data ta-dir=1 \ 46 | +vpn.data verify-x509-name=name:access.is 47 | ``` 48 | 49 | ## WireGuard 50 | 51 | The recommended way to configure a WireGuard connection is to place a configuration file in a folder readable by the network-manager snap, such as SNAP_DATA or SNAP_COMMON folders, and to import the configuration with a command similar to the following: 52 | 53 | ```bash 54 | nmcli c import type WireGuard file /var/snap/nm-vpn-client/common/wg.conf 55 | ``` 56 | 57 | As with an OpenVPN connection, it is also possible to create a WireGuard connection using only `nmcli` with multiple parameters. Unfortunately, configuring peers in this way is not currently possible (see [WireGuard in NetworkManager](https://blogs.gnome.org/thaller/2019/03/15/WireGuard-in-networkmanager/)). 58 | 59 | ## Configuring a VPN programmatically 60 | 61 | To create a VPN connection programmatically, that is, from another snap, the user snap must define a [content interface](https://snapcraft.io/docs/content-interface). The connection must have a slot that connects to the `vpn-creds` plug defined in the network-manager snap. 62 | 63 | Once connected, any files necessary for the connection can be placed into the directory shared by the content interface. This folder is seen by the Network Manager snap `/var/snap/network-manager/common/creds`, which means that file path configuration also needs also use this prefix. After that, a connection can be created using Network Manager's `dbus` interface where a connected network-manager plug is required. 64 | 65 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-wifi-access-points.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-configure-wifi-access-points)= 2 | # Configure Wi-Fi access points 3 | 4 | It is possible to create Wi-Fi Access Points with the network-manager snap. This can be done by running 5 | ```bash 6 | nmcli d wifi hotspot ifname ssid password 7 | ``` 8 | where `` is the wifi network interface, `` is the SSID for the AP that we are creating and that will be visible to devices connecting to it, and `` is the access password (that needs to have between 8-63 characters or 64 hexadecimal characters). NM will create a connection called ' `Hotspot ` ' if the command is successful. 9 | 10 | The created AP offers by default a shared connection, so devices connected to it should be able to access the Internet if the device providing the AP has access too. 11 | 12 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/configure-wifi-connections.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-configure-wifi-connections)= 2 | # Configure Wi-Fi connections 3 | 4 | This section explains how to establish a Wi-Fi connection. It covers creating and modifying connections as well as directly connecting. 5 | 6 | ## Establish a connection 7 | 8 | This section will show how to establish a wifi connection to the wireless network. Note that directly connecting will implicitly create a connection (that can be seen with "nmcli c"). The naming of such will follow "SSID N" pattern, where N is a number. 9 | 10 | First, determine the name of the Wi-Fi interface: 11 | 12 | ```bash 13 | $ nmcli d 14 | DEVICE TYPE STATE CONNECTION 15 | ... 16 | wlan0 wifi disconnected -- 17 | ``` 18 | 19 | Make sure the Wi-Fi radio is on (which is its default state): 20 | 21 | ```bash 22 | nmcli r wifi on 23 | ``` 24 | 25 | Then, list the available Wi-Fi networks: 26 | 27 | ```bash 28 | $ nmcli d wifi list 29 | * SSID MODE CHAN RATE SIGNAL BARS SECURITY 30 | ... 31 | my_wifi Infra 5 54 Mbit/s 89 ▂▄▆█ WPA2 32 | ``` 33 | 34 | As an example, to connect to the access point 'my_wifi', you would use the following command: 35 | 36 | ```bash 37 | nmcli d wifi connect my_wifi password 38 | ``` 39 | 40 | \ is the password for the connection which needs to have 8-63 characters or 64 hexadecimal characters to specify a full 256-bit key. 41 | 42 | ## Connect to a hidden network 43 | 44 | A hidden network is a normal wireless network that simply does not broadcast it's SSID unless solicited. This means that its name cannot be searched and must be known from some other source. 45 | 46 | Issue the following command to create a connection associated with a hidden network : 47 | 48 | ```bash 49 | nmcli c add type wifi con-name ifname wlan0 ssid 50 | nmcli c modify wifi-sec.key-mgmt wpa-psk wifi-sec.psk 51 | ``` 52 | 53 | Now you can establish a connection by typing: 54 | 55 | ```bash 56 | nmcli c up 57 | ``` 58 | 59 | \ is an arbitrary name given to the connection and is the password to the network. It needs to have between 8-63 characters or 64 hexadecimal characters in order to specify a full 256-bit key. 60 | 61 | ## Further information 62 | 63 | You will find further information and more detailed examples on following pages: 64 | 65 | - https://developer.gnome.org/NetworkManager/unstable/nmcli.html 66 | 67 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/edit-connections.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-edit-connections)= 2 | # Edit connections 3 | 4 | This section shows how to use the network-manager built-in editor to modify connections as well as provide a reference for changing some of the settings. 5 | 6 | ## Using nmcli Console 7 | Aside from offering the possibility to manage and modify the network connections using the command-line, network-manager offers a built-in, interactive console to achieve the same. In order to use it type: 8 | 9 | ```bash 10 | nmcli connection edit 11 | ``` 12 | 13 | It will bring up an interactive console. In the first step you will be prompted to enter the connection type. The list of valid connection types will be displayed on the screen. Once you select one you will be taken to the nmcli console where you have the possibility to modify its parameters. 14 | 15 | Alternatively, if you know the valid connection types, you could jump straight to the nmcli console by providing the type as a parameter: 16 | 17 | ```bash 18 | nmcli connection edit type 19 | ``` 20 | 21 | where must be a valid connection type such as 'wifi'. 22 | 23 | An attempt to edit the wifi connection type would look like: 24 | ```bash 25 | $ nmcli c edit 26 | 27 | Valid connection types: generic, 802-3-ethernet (ethernet), pppoe, 28 | 802-11-wireless (wifi), wimax, gsm, cdma, infiniband, adsl, bluetooth, vpn, 29 | 802-11-olpc-mesh (olpc-mesh), vlan, bond, team, bridge, bond-slave, team-slave, 30 | bridge-slave, no-slave, tun, ip-tunnel, macvlan, vxlan 31 | Enter connection type: wifi 32 | 33 | ===| nmcli interactive connection editor |=== 34 | 35 | Adding a new '802-11-wireless' connection 36 | 37 | Type 'help' or '?' for available commands. 38 | Type 'describe [.]' for detailed property description. 39 | 40 | You may edit the following settings: connection, 802-11-wireless (wifi), 41 | 802-11-wireless-security (wifi-sec), 802-1x, ipv4, ipv6 42 | nmcli> 43 | ``` 44 | 45 | From now on it is possible to edit the wifi connection settings. The list of settings is provided as in the example above. The nmcli console offers a set of commands that can be used to navigate between settings. To get the list of available commands type 'help' or '?' 46 | 47 | ```bash 48 | nmcli> ? 49 | ``` 50 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/explore-network-status.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-explore-network-status)= 2 | # Explore network status 3 | 4 | This section shows how to use the _nmcli_ command line tool to examine the status of NetworkManager’s connections and devices. 5 | 6 | Show the status of devices known to NetworkManager: 7 | 8 | ```bash 9 | $ nmcli d 10 | nmcli d 11 | DEVICE TYPE STATE CONNECTION 12 | enp0s31f6 ethernet connected Wired connection 1 13 | docker0 bridge connected docker0 14 | lo loopback unmanaged -- 15 | ``` 16 | 17 | Add `--help` for more details on a given option. 18 | 19 | To show the current status of each of NetworkManager’s connections: 20 | 21 | ``` 22 | $ nmcli c 23 | NAME UUID TYPE DEVICE 24 | Wired connection 1 59b3aab1-f9a8-3bee-8fd2-2497a1dcd99c ethernet enp0s31f6 25 | docker0 b13e1f13-c23c-47c3-9b3e-ca43ecd79e79 bridge docker0 26 | ``` 27 | 28 | Finally, we can see the state of radio interfaces, including Wi-Fi and WWAN (cellular) with the _radio_ argument: 29 | 30 | ```bash 31 | $ nmcli r 32 | WIFI-HW WIFI WWAN-HW WWAN 33 | enabled enabled enabled enabled 34 | ``` 35 | 36 | It is important to make sure that Wi-Fi/WWAN radios are enabled so the respective connection types can establish a connection (we will specify how to this in following sections). As with the other commands, “--help” shows usage information. 37 | 38 | Observe NetworkManager activity (changes in connectivity state, devices or connection properties): 39 | 40 | ```bash 41 | nmcli monitor 42 | ``` 43 | 44 | See nmcli connection monitor and nmcli device monitor to watch for changes in certain connections or devices. 45 | 46 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-index)= 2 | # How-to guides 3 | 4 | Network Manager has many different capabilities, and can adapt to many different networking environments. 5 | 6 | ## Configuration 7 | 8 | Instructions on configuring Network Manager for your environment. 9 | 10 | - [Cellular connections](configure-cellular-connections.md) 11 | - [Shared connections](configure-shared-connections.md) 12 | - [VPN connections](configure-vpn-connections.md) 13 | - [Wi-Fi connections](configure-wifi-connections.md) 14 | - [Wi-Fi access points](configure-wifi-access-points.md) 15 | 16 | ## Connection management 17 | 18 | Inspect and explore a connection after it's been configured. 19 | 20 | - [Edit connections](edit-connections.md) 21 | - [Manage routing tables](routing-tables.md) 22 | - [Message logging](message-logging.md) 23 | - [Explore network status](explore-network-status.md) 24 | - [Network Manager and Netplan](networkmanager-and-netplan.md) 25 | 26 | ```{toctree} 27 | :hidden: 28 | :titlesonly: 29 | :maxdepth: 2 30 | :glob: 31 | 32 | * 33 | */index 34 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/message-logging.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-how-to-guides-message-logging)= 2 | # Message logging 3 | 4 | This section shows how to modify the logging levels by NetworkManager. 5 | 6 | NetworkManager supports on the fly changing of the logging levels and allows for a fine grained control over what is logged. 7 | 8 | First check what is the current logging setup, type: 9 | ```bash 10 | nmcli general logging 11 | ``` 12 | As a result you will be presented with the information about the current configuration: 13 | 14 | ``` 15 | LEVEL DOMAINS 16 | INFO PLATFORM,RFKILL,ETHER,WIFI,BT,MB,DHCP4,DHCP6,PPP,IP4,IP6,AUTOIP4,DNS,VPN,SHARING,SUPPLICANT,AGENTS,SETTINGS,SUSPEND,CORE,DEVICE,OLPC,INFINIBAND,FIREWALL,ADSL,BOND,VLAN,BRIDGE,TEAM,CONCHECK,DCB,DISPATCH,AUDIT,SYSTEMD 17 | ``` 18 | It is possible to change the level either globally or for each domain separately. The command to achieve this is: 19 | 20 | ```bash 21 | nmcli general logging [level [domain ]] 22 | ``` 23 | 24 | The is the desired log level. You can choose from the following: 25 | 26 | - **ERR**: will log only critical errors 27 | - **WARN**: will log warning messages 28 | - **INFO**: will log various informational messages 29 | - **DEBUG**: enables verbose logging for debugging purposes 30 | - \ is the category of messages that shall be logged with given severity. 31 | - **Wi-Fi** will include only Wi-Fi related messages 32 | - **IP4** will include only IPv4 related messages, and so on. 33 | 34 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/networkmanager-and-netplan.md: -------------------------------------------------------------------------------- 1 | # NetworkManager and Netplan 2 | 3 | Ubuntu Core's default Netplan configuration defers networking to _networkd_. 4 | 5 | When [Network Manager](https://help.ubuntu.com/community/NetworkManager) is installed (`snap install network-manager`), a new Netplan configuration replaces networkd with _network-manager_, taking control of all networking devices. 6 | 7 | This behaviour can be controlled with the `defaultrenderer` snap option. By default, this is set to `true` to allow network-manger to control networking. If set to `false`, network-manager reverts the default Netplan configuration, giving control of network devices back to networkd. 8 | 9 | ```bash 10 | snap set network-manager defaultrenderer=false 11 | ``` 12 | 13 | Note that only devices explicitly configured within Netplan configuration files, usually only ethernet or wifi, are given back to networkd. 14 | 15 | ## YAML backend 16 | 17 | From _core20_ onwards, network-manager been modified to use a YAML backend that's based on _libnetplan_ functionality. 18 | 19 | The YAML backend replaces the keyfile format used by Network Manager with `/etc/Netplan/*.yaml`. 20 | 21 | The default configuration, for example, can be output by running the `cat sudo cat /etc/netplan/00-snapd-config.yaml` to produce show following output: 22 | 23 | ```yaml 24 | # This is the network config written by 'console-conf' 25 | network: 26 | ethernets: 27 | enp0s2: 28 | dhcp4: true 29 | version: 2 30 | ``` 31 | 32 | On boot the Netplan.io generator processes all of the YAML files and renders them into the corresponding a Network Manager configuration in `/run/NetworkManager/system-connections`. The usual `Netplan generate/try/apply` can be used to re-generate this configuration after the YAML was modified. 33 | 34 | If a connection profile is modified or created from within Network Manager, such as updating a Wi-Fi password with `nmcli`, Network Manager will create an ephemeral keyfile that will be immediately converted to Netplan YAML and stored in `/etc/Netplan`. Network Manager automatically calls `Netplan generate` to re-process the current YAML configuration to render Network Manager connection profiles in `/run/NetworkManager/system-connections`. 35 | 36 | The system wide network configuration can be read with `sudo netplan get`: 37 | 38 | ```yaml 39 | network: 40 | version: 2 41 | renderer: NetworkManager 42 | ethernets: 43 | enp0s2: 44 | dhcp4: true 45 | ``` 46 | 47 | System wide network settings can be modified with `netplan set`: 48 | 49 | ```bash 50 | sudo netplan set ethernets.enp0s2.addresses=[10.0.2.15/24] 51 | ``` 52 | 53 | Configuration options that are not supported by the Network Manager YAML backend are stored in a `networkmanager.passthrough` YAML mapping to ensure they are not lost during the Netplan conversion. 54 | 55 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/how-to-guides/routing-tables.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-routing-tables)= 2 | # Manage routing tables 3 | 4 | This section describes the way to setup routing table as well as it explains the logic used to prioritize interfaces. 5 | 6 | The routing table is stored in the kernel which merely acts upon it. The route itself is set by the user-space tools. There is no preference as any tool created for this reason will do. It can be either a DHCP client, ip command or route command. 7 | 8 | It is important to understand that NetworkManager changes the routing table whenever it creates a new connection. 9 | 10 | Routing table acts as a junction and is there to show where the different network subnets will be routed to. An example of a routing table is shown below. 11 | 12 | ```bash 13 | $ ip route \ 14 | default via 10.0.0.1 dev wlp3s0 proto static metric 600 \ 15 | 10.0.0.0/24 dev wlp3s0 proto kernel scope link src 10.0.0.73 metric 600 \ 16 | 10.0.1.0/24 dev lxcbr0 proto kernel scope link src 10.0.1.1 \ 17 | 169.254.0.0/16 dev docker0 scope link metric 1000 linkdown \ 18 | 172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown \ 19 | 192.168.122.0/24 dev virbr0 proto kernel scope link src 192.168.122.1 linkdown 20 | ``` 21 | 22 | The first column is the subnet with the "default" being a wildcard for everything else. The "via" fragment points to the \ however when it is missing it indicates that that network is connected directly and instead it describes a source address. 23 | 24 | The metric field/column translates to the number of hops required to reach the destination and is used to determine which route shall be preferred when there are more than one route available for a specific destination. Since this value is related to the concept of distance, the lower it's value is the better. 25 | 26 | The metric value can be set manually however when NetworkManager creates a connection the following defaults are applied: 27 | 28 | * Ethernet is preferred over Wi-Fi 29 | * Wi-Fi is preferred over WWAN 30 | 31 | ## Editing the routing tables 32 | 33 | The routing table can be added or modified using the standard `ip` command which is available on Ubuntu Core. You can find more information on its [man page](https://linux.die.net/man/8/ip). 34 | 35 | Separately it is possible to modify routing information per single connection using the nmcli tool. The parameters such as: gateway, routes and metrics can be modified. 36 | 37 | The following options are responsible: 38 | 39 | ``` 40 | ipv4.gateway: 41 | ipv4.routes: 42 | ipv4.route-metric: 43 | 44 | ipv6.gateway: 45 | ipv6.routes: 46 | ipv6.route-metric: 47 | ``` 48 | 49 | These options can be modified in a following way: 50 | 51 | ```bash 52 | $ nmcli connection modify +ipv4.routes ipv4.gateway 53 | $ nmcli connection modify ipv4.route-metric 54 | ``` 55 | 56 | Where `` is the connection name. You can obtain it by listing available connections on the system: 57 | 58 | ```bash 59 | $ nmcli c show 60 | ``` 61 | 62 | * `` is the destination network provided as a static IP address, subnet or "default". 63 | * `` is the new gateway information. is the new metric information. 64 | 65 | Note that this kind of changes can be made separately for each connection thus it is possible to provide a fine grained control over how the packets directed to different networks are routed. 66 | 67 | It is also important to understand that bringing up and down connections with different values set for these options is in fact changing the routing table. 68 | 69 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-index)= 2 | # Network-Manager 3 | 4 | Network Manager is a system network service that manages your network devices and connections and attempts to keep network connectivity active when available. It manages Ethernet, Wi-Fi, mobile broadband (WWAN) and PPPoE devices while also providing VPN integration with a variety of different VPN services. 5 | 6 | By default network management on [Ubuntu Core](https://www.ubuntu.com/core) is handled by systemd's [networkd](https://www.freedesktop.org/software/systemd/man/systemd-networkd.service.html) and [netplan](https://launchpad.net/netplan). However, when Network Manager is installed, it will take control of all networking devices in the system by creating a netplan configuration file in which it sets itself as the default network renderer. 7 | 8 | ## What NetworkManager Offers 9 | 10 | The upstream Network Manager project offers a wide range of features and most, but not all of them, are available in the snap package at the moment. 11 | 12 | Currently we provide support for the following high level features: 13 | 14 | * Wi-Fi connectivity 15 | * WAN connectivity (together with Modem Manager) 16 | * Ethernet connectivity 17 | * Wi-Fi access point creation 18 | * Shared connections 19 | * VPN connections 20 | 21 | ## Upstream documentation 22 | 23 | Documentation for the upstream project can be found at [https://wiki.gnome.org/Projects/NetworkManager](https://wiki.gnome.org/Projects/NetworkManager). 24 | 25 | ```{toctree} 26 | :hidden: 27 | :titlesonly: 28 | :maxdepth: 2 29 | :glob: 30 | 31 | * 32 | */index 33 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/install-networkmanager.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-install-networkmanager)= 2 | # Install NetworkManager 3 | 4 | 5 | The NetworkManager snap is currently available from the Snap Store. At can be installed on any system that supports snaps but is only recommended on [Ubuntu Core](/index) at the moment. 6 | 7 | You can install the snap with the following command: 8 | ```bash 9 | snap install network-manager 10 | ``` 11 | All necessary plugs and slots will be automatically connected within the installation process. You can verify this with: 12 | 13 | ```bash 14 | snap connections network-manager 15 | ``` 16 | 17 | **NOTE:** The *network-manager:modem-manager* plug only gets connected when the *modem-manager* snap is installed too. Otherwise it stays disconnected. Similarly, there is a *network-manager:wpa* plug in case we would want to use a custom wpa supplicant snap instead of the one supplied by the core snap (this is not generally recommended). 18 | 19 | Once the installation has successfully finished the NetworkManager service is running in the background. You can check its current status with 20 | 21 | ```bash 22 | systemctl status snap.network-manager.networkmanager.service 23 | ``` 24 | 25 | Now you have NetworkManager successfully installed. 26 | 27 | ## Tracks and channels 28 | 29 | The network-manager snap has currently five tracks, and with the exception of the ‘latest’ and ‘1.10’ track, the track name will refer to the version of the base snap used. 30 | 31 | * **24**: Contains upstream 1.46.0 and has a core24 base. 32 | * **22**: Contains upstream 1.36.6 and has a core22 base. Nowadays, this is the one installed by default if the channel is not specified when running `snap install` . 33 | * **20** : Contains upstream 1.22.10 and has a core20 base. 34 | * **1.10** : Contains upstream 1.10.6 and has a core18 base. The track name refers to the upstream version. More modern releases have changed the convention so the track now refers to the base snap. 35 | * **latest** : Contains upstream 1.2.2 and has a core16 base. Despite the unfortunate name (there are historical reasons for that) it is the oldest version. 36 | 37 | All these tracks are available with the usual risks: stable, candidate, beta, and edge, but only the stable version should be used for production devices. The meaning of the other risk levels is internal to the development team of the network-manager snap. 38 | 39 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/release-notes.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-release-notes)= 2 | # Release Notes 3 | 4 | 5 | You can check with the following command which version you have currently installed: 6 | 7 | ``` 8 | $ snap info network-manager 9 | name: network-manager 10 | summary: Network Manager 11 | publisher: Canonical✓ 12 | store-url: https://snapcraft.io/network-manager 13 | contact: https://help.ubuntu.com/community/NetworkManager 14 | license: unset 15 | description: | 16 | NetworkManager is a system network service that manages your network 17 | devices and connections, attempting to keep active network connectivity 18 | when available. It manages ethernet, Wi-Fi, mobile broadband (WWAN) and 19 | PPPoE devices, provides VPN integration with a variety of different 20 | VPN serivces. 21 | Please find the source code for this track at: 22 | https://code.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager/+ref/snap-1.10 23 | commands: 24 | - network-manager.nmcli 25 | - network-manager.nmtui 26 | - network-manager.nmtui-connect 27 | - network-manager.nmtui-edit 28 | - network-manager.nmtui-hostname 29 | services: 30 | network-manager.networkmanager: simple, enabled, active 31 | snap-id: RmBXKl6HO6YOC2DE4G2q1JzWImC04EUy 32 | tracking: 1.10/stable 33 | refresh-date: today at 10:18 UTC 34 | channels: 35 | 1.10/stable: 1.10.6-7 2020-06-29 (564) 4MB - 36 | 1.10/candidate: 1.10.6-7 2020-06-29 (564) 4MB - 37 | 1.10/beta: 1.10.6-7 2020-06-25 (564) 4MB - 38 | 1.10/edge: 1.10.6-5-dev 2020-04-06 (542) 4MB - 39 | latest/stable: 1.2.2-25 2020-06-22 (554) 4MB - 40 | latest/candidate: 1.2.2-25 2020-06-19 (554) 4MB - 41 | latest/beta: 1.2.2-26 2020-07-07 (573) 4MB - 42 | latest/edge: 1.2.2-26-dev 2020-07-07 (569) 4MB - 43 | 20/stable: – 44 | 20/candidate: – 45 | 20/beta: 1.22.10-1 2020-06-25 (561) 5MB - 46 | 20/edge: 1.22.10-2-dev 2020-07-08 (580) 5MB - 47 | installed: 1.10.6-7 (564) 4MB - 48 | ``` 49 | 50 | The detailed changelog for each revision can be consulted in the sources for each track: 51 | 52 | * For track 20, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager/tree/ChangeLog?h=snap-20) 53 | * For track 1.10, [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager/tree/ChangeLog?h=snap-1.10) 54 | * For track latest (note again this is not actually the more modern NM), [here](https://git.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager/tree/ChangeLog) 55 | 56 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/network-manager/report-a-bug.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-network-manager-reference-report-a-bug)= 2 | # Report a Bug 3 | 4 | Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug). 5 | 6 | When submitting a bug report, please attach system log coming from the journal: 7 | 8 | ```bash 9 | journalctl --no-pager > system-log 10 | ``` 11 | 12 | And the output of the following two commands: 13 | 14 | ```bash 15 | nmcli d 16 | nmcli c 17 | ``` 18 | It is a good idea to set the log level to DEBUG so that the verbose information is provided. To do this for NetworkManager please see the [Logging Messages](/explanation/system-snaps/network-manager/how-to-guides/message-logging) page. 19 | 20 | If there is a modem and the modem-manager snap is installed, also add the output of 21 | ```bash 22 | sudo modem-manager.mmcli -m 23 | ``` 24 | With being the modem number as reported by 25 | ```bash 26 | sudo modem-manager.mmcli -L 27 | ``` 28 | 29 | -------------------------------------------------------------------------------- /docs/how-to-guides/container-deployment/build-an-image-for-docker-deployment.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-container-deployment-build-an-image-for-docker-deployment)= 2 | # Build an image for Docker deployment 3 | 4 | Ubuntu Core runs applications as snaps, and running the Docker Engine as a snap is no exception. 5 | 6 | To run Docker containers on a running Ubuntu Core instance, install the Docker snap and [run your docker commands](/how-to-guides/container-deployment/run-a-docker-container). 7 | 8 | You can even create a [companion snap](/explanation/docker-companion-snap) that [runs the container](/how-to-guides/container-deployment/deploy-docker-from-a-snap) and takes care of updates to the [bundled container image](/how-to-guides/container-deployment/package-docker-images-in-a-snap). 9 | 10 | To ship containerised applications with Ubuntu Core, you need to create a custom image. The custom image can then be used to create bootable media and can automate deployment of a production system. 11 | 12 | To create a custom Ubuntu Core image with one or more containerised Docker applications, the applications need to be first packaged as [Docker companion snaps](/explanation/docker-companion-snap), listed in the model assertion along with the Docker snap, and given the right permissions to operate. 13 | 14 | The image may also include container configurations. 15 | 16 | Start by creating a [model assertion](/reference/assertions/model). Add the Docker snap and all other companion snaps to the list: 17 | 18 | ```json 19 | { 20 | "name": "docker", 21 | "type": "app", 22 | "default-channel": "latest/stable", 23 | "id": "sLCsFAO8PKM5Z0fAKNszUOX0YASjQfeZ" 24 | }, 25 | { 26 | "name": "", 27 | "type": "app", 28 | "default-channel": "", 29 | "id": "" 30 | } 31 | ``` 32 | 33 | This example only lists one companion snap, available in a snap store. A single companion snap could manage multiple Docker containers. 34 | 35 | Each companion snap needs access to the Docker snap to operate. We grant the access via [snap interface](https://snapcraft.io/docs/supported-interfaces) connections between the snaps. In order to automate the granting of access, each companion snap must be published to a store and have an ID. There are two ways to configure this automated interface connection: via an auto-connection assertion defined in a snap store, or via a custom gadget. Here we cover the method via a custom gadget. 36 | 37 | Read the [gadget snaps documentation](https://snapcraft.io/docs/the-gadget-snap) to get familiar with the concepts and instructions. Inside the `gadget.yaml` file, adapt and add the following to `connections`, for each companion snap: 38 | 39 | ```yaml 40 | connections: 41 | # Needed to communicate with Docker over the Unix socket 42 | - slot: sLCsFAO8PKM5Z0fAKNszUOX0YASjQfeZ:docker-daemon 43 | plug: :docker 44 | # Needed to use the docker CLI 45 | - slot: sLCsFAO8PKM5Z0fAKNszUOX0YASjQfeZ:docker-executables 46 | plug: :docker-executables 47 | ``` 48 | 49 | Container configuration can be passed on to the companion snap, via [snap configuration options](https://snapcraft.io/docs/adding-snap-configuration). To set such configurations in the Ubuntu Core image, add them to the same `gadget.yaml` file, under `defaults`: 50 | 51 | ```yaml 52 | defaults: 53 | : 54 | key: value 55 | ``` 56 | 57 | Finally, replace the default gadget snap listed in the model assertion with the custom one that has the connections: 58 | 59 | ```json 60 | { 61 | "name": "", 62 | "type": "gadget", 63 | "default-channel": "", 64 | "id": "" 65 | } 66 | ``` 67 | 68 | Omit `default-channel` and `id` if you want to [build the image using a custom gadget snap](/how-to-guides/image-creation/add-custom-snaps) that hasn't been uploaded to a store. 69 | 70 | -------------------------------------------------------------------------------- /docs/how-to-guides/container-deployment/index.md: -------------------------------------------------------------------------------- 1 | # Container deployment 2 | 3 | Ubuntu Core has been developed specifically to leverage the power of snap packages, with their autonomous upgrades and confined sandbox. 4 | 5 | However, Ubuntu Core can also be used to run and deploy Docker container images, either from the command line or embedded within an Ubuntu Core image. 6 | 7 | ## Deploying Docker 8 | 9 | Install and run Docker from within the Ubuntu Core environment. Build a snap which embeds the container images you wish to deploy from a device. 10 | 11 | - [Run a Docker container](/how-to-guides/container-deployment/run-a-docker-container) 12 | - [Deploy Docker containers from a snap](/how-to-guides/container-deployment/deploy-docker-from-a-snap) 13 | 14 | ## Packaging Docker 15 | 16 | How Docker images can be bundled inside snaps to be deployed together with other resources within the package. 17 | 18 | Ship containerised applications with Ubuntu Core by building a custom image that can then be used to create bootable media and can automate deployment of a production system. 19 | 20 | 21 | - [Package Docker images in a snap](/how-to-guides/container-deployment/package-docker-images-in-a-snap) 22 | - [Build an image for Docker deployment](build-an-image-for-docker-deployment) 23 | 24 | 25 | ```{toctree} 26 | :hidden: 27 | :titlesonly: 28 | :maxdepth: 2 29 | :glob: 30 | 31 | Run a Docker container 32 | Deploy Docker from a snap 33 | Package Docker images in a snap 34 | Build an image for Docker deployment 35 | -------------------------------------------------------------------------------- /docs/how-to-guides/container-deployment/package-docker-images-in-a-snap.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-container-deployment-package-docker-images-in-a-snap)= 2 | # Package Docker images in a snap 3 | 4 | Docker containers can be deployed on Ubuntu Core from [the command-line](run-a-docker-container), or via a [Docker companion snap](/explanation/docker-companion-snap). 5 | 6 | This guide explains how Docker images can be bundled inside snaps to be deployed together with other resources within the package. 7 | 8 | Downloading Docker images from an online registry during the installation is a common approach. There are however situations where this isn't desired: 9 | - Air-gapped environment with no internet connection 10 | - Insecure Docker registry or untrusted image publisher 11 | - Local Docker image including proprietary software 12 | - Docker image built together with the snap 13 | 14 | Consequently, bundling the Docker image inside a snap is useful for both existing and locally built images. 15 | 16 | Snaps are signed, which means the entire package, including the Docker image, is a verifiable artefact that can be pulled from an online or on-prem store, built into Ubuntu Core images, or passed around as standalone snaps. 17 | 18 | Building a snap that contains and uses an existing image involves a few steps. 19 | 20 | ## Save the image to a file 21 | 22 | This can be done before or during the snap's build. We'll do this before the build, assuming that a Docker Engine is available to the host, rather than adding one to the snap's build environment. 23 | 24 | To save our image to a file, we should first make sure it is loaded into the Docker Engine. 25 | 26 | The image is loaded to the engine when built locally (e.g. `docker build --tag myapp .`) or pulled from a registry (e.g. `docker pull `): 27 | 28 | ```console 29 | $ docker images 30 | REPOSITORY TAG IMAGE ID CREATED SIZE 31 | myapp latest 93c368f790a8 2 minutes ago 125MB 32 | ``` 33 | 34 | Let's save the image as a tar file: 35 | ``` 36 | $ docker save --output myapp.tar myapp 37 | 38 | $ du -h myapp.tar 39 | 123M myapp.tar 40 | ``` 41 | 42 | Don't worry about the size; this gets significantly smaller when compressed inside the snap. Moreover, upgrades to the snap will only deploy the delta, calculated on the compressed package, rather than the whole blob. 43 | 44 | ## Add the image to the snap 45 | 46 | Make sure that the snap has a `part` that sources the image. 47 | 48 | For example, with a part that sources all the project files: 49 | ```yaml 50 | parts: 51 | all-files: 52 | plugin: dump 53 | source: . 54 | ``` 55 | The tar file would be made available inside the snap, on target at `$SNAP/myapp.tar`. 56 | 57 | ## Load the image before creating the container 58 | 59 | Add the following command to load the image to the Docker Engine before creating the container: 60 | ```bash 61 | docker load --input $SNAP/myapp.tar 62 | ``` 63 | 64 | This could be in the service's command or the install/refresh hooks. 65 | 66 | That's it. You should now be able to build the snap as usual. 67 | Refer below for a complete example. 68 | 69 | ## Example: RabbitMQ Docker companion snap 70 | 71 | Let's take the snap created in the [Docker companion snap](deploy-docker-from-a-snap) guide. 72 | 73 | With that snap, the Docker image was pulled from DockerHub on first startup and after every refresh (upgrade/downgrade). This is because the image wasn't available locally. 74 | 75 | What we need to do is to make sure the image is packaged inside the snap and loaded into the Docker Engine before the container creation. 76 | 77 | On the host, pull the image to load it into the Docker Engine: 78 | ```bash 79 | docker pull rabbitmq:3.13-management 80 | ``` 81 | 82 | Create the `snap/local/image` directory: 83 | ```bash 84 | mkdir snap/local/image 85 | ``` 86 | 87 | Save the image inside it: 88 | ```bash 89 | docker save --output snap/local/image/rabbitmq.tar rabbitmq:3.13-management 90 | ``` 91 | 92 | The `image` directory gets added to the snap because of the existing `local` part defined in `snapcraft.yaml`. 93 | 94 | In `snap/local/bin/run.sh`: 95 | - Add the following `docker load` command right before creating the container: 96 | ```bash 97 | if [ ... ]; then 98 | ... 99 | 100 | docker load --input $SNAP/image/rabbitmq.tar 101 | 102 | docker create \ 103 | ... 104 | fi 105 | ``` 106 | -------------------------------------------------------------------------------- /docs/how-to-guides/container-deployment/run-a-docker-container.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-container-deployment-run-a-docker-container)= 2 | # Run a Docker container 3 | 4 | Ubuntu Core is made up entirely of snap packages. To run Docker containers, you need to have the Docker Engine installed as a snap. 5 | 6 | This page assumes that you have installed Ubuntu Core via a [pre-built image](/tutorials/try-pre-built-images/index) and would like to install the Docker Engine and run containers from the command line. 7 | 8 | ## Install Docker Engine 9 | After logging into the Ubuntu Core device, install the Docker Engine snap by running: 10 | ```shell 11 | sudo snap install docker 12 | ``` 13 | 14 | ## Set up permissions 15 | 16 | The installation should automatically connect the [`home` interface](https://snapcraft.io/docs/home-interface) to grant the Docker snap access to the non-hidden files in the user's home directory. 17 | 18 | The list of interface connections can be verified by running `snap connections docker`. 19 | 20 | If the home interface hasn't been auto-connected (such as on Ubuntu Core 16), connect it manually by running: 21 | ```shell 22 | sudo snap connect docker:home 23 | ``` 24 | 25 | ```{admonition} Docker file access 26 | :class: tip 27 | The `docker` command only has access to your home directory. All files such as `Dockerfile`, `docker-compose.yaml` or `.env` should be inside home. 28 | ``` 29 | 30 | ## Add credentials for registry 31 | 32 | If you use certificates to access a private registry, add these certificates into: 33 | ``` 34 | /var/snap/docker/current/etc/docker/certs.d/ 35 | ``` 36 | 37 | ## Run the container 38 | 39 | Now you can run a container like you would normally do it with Docker: 40 | ``` 41 | $ sudo docker run hello-world 42 | Unable to find image 'hello-world:latest' locally 43 | latest: Pulling from library/hello-world 44 | 478afc919002: Pull complete 45 | Digest: sha256:a26bff933ddc26d5cdf7faa98b4ae1e3ec20c4985e6f87ac0973052224d24302 46 | Status: Downloaded newer image for hello-world:latest 47 | 48 | Hello from Docker! 49 | This message shows that your installation appears to be working correctly. 50 | 51 | To generate this message, Docker took the following steps: 52 | 1. The Docker client contacted the Docker daemon. 53 | 2. The Docker daemon pulled the "hello-world" image from the Docker Hub. 54 | (arm64v8) 55 | 3. The Docker daemon created a new container from that image which runs the 56 | executable that produces the output you are currently reading. 57 | 4. The Docker daemon streamed that output to the Docker client, which sent it 58 | to your terminal. 59 | 60 | To try something more ambitious, you can run an Ubuntu container with: 61 | $ docker run -it ubuntu bash 62 | 63 | Share images, automate workflows, and more with a free Docker ID: 64 | https://hub.docker.com/ 65 | 66 | For more examples and ideas, visit: 67 | https://docs.docker.com/get-started/ 68 | 69 | ``` 70 | 71 | > :information_source: You have to run all docker commands with `sudo` because it is not possible to add a user to the docker group on Ubuntu Core. 72 | 73 | If you prefer using Docker Compose, that is also available: 74 | ``` 75 | sudo docker compose 76 | ``` 77 | 78 | --- 79 | 80 | Another way to run Docker containers on Ubuntu Core is via companion snaps. This means each container will be managed by its own snap package, containing its configuration. Such a package has a safer upgrade path, with rollback of config and data if something went wrong. To learn how to create such a companion snap, refer [here](/how-to-guides/container-deployment/deploy-docker-from-a-snap). 81 | 82 | -------------------------------------------------------------------------------- /docs/how-to-guides/image-creation/add-a-splash-screen.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-image-creation-add-a-splash-screen)= 2 | # Add a splash screen 3 | 4 | By default, Ubuntu Core does not display a splash screen when a device is booting or shutting down. However, on Ubuntu Core 22 (and later), a splash screen can be enabled, either to display the built-in Ubuntu Core branding, or to display custom vendor branding or imagery. 5 | 6 | ![Ubuntu Core Splash](https://assets.ubuntu.com/v1/72b8914b-core-splash_01.png) 7 | 8 | Ubuntu Core’s splash screen is based on Ubuntu’s [Plymouth-based splash screen](https://wiki.ubuntu.com/Plymouth#Splash_Theme) implementation. It’s enabled by adding `quiet splash` as a [kernel boot parameter](/reference/kernel-boot-parameters): 9 | 10 | ```yaml 11 | quiet splash 12 | ``` 13 | 14 | On Ubuntu Core 22 and later, when using the default GNU GRUB bootloader, kernel boot parameters can be configured either in the [Gadget snap](/reference/gadget-snap-format), or through [system options](https://snapcraft.io/docs/system-options). See [Modifying kernel boot parameters](/how-to-guides/manage-ubuntu-core/modify-kernel-options) for further details on each process. 15 | 16 | ## Customised splash screen 17 | 18 | The splash screen can be customised in two different ways, either by including a new logo or image file, or by completely replacing the Plymouth theme used to generate the splash screen. 19 | 20 | ### New vendor logo or image 21 | 22 | ![Ubuntu Core vendor splash screen, 50%](https://assets.ubuntu.com/v1/3410143e-core-splash_02.png) 23 | 24 | A PNG-formatted vendor logo, or any other PNG-formatted image, can be placed within a new `/splash` directory in the root of the [Gadget snap](/reference/gadget-snap-format). The image file must be called `vendor-logo.png`: 25 | 26 | ```yaml 27 | . 28 | ├── cmdline.extra 29 | ├── grub.conf 30 | ├── grubx64.efi 31 | ├── meta 32 | │ ├── gadget.yaml 33 | │ ├── gui 34 | │ ├── hooks 35 | │ │ └── configure 36 | │ └── snap.yaml 37 | ├── pc-boot.img 38 | ├── pc-core.img 39 | ├── shim.efi.signed 40 | ├── snap 41 | │ ├── command-chain 42 | │ │ └── snapcraft-runner 43 | │ └── hooks 44 | │ └── configure 45 | └── splash 46 | └── vendor-logo.png 47 | ``` 48 | 49 | The image will be scaled accordingly and images with a 2:1 aspect ratio work best (such as images with resolution of 800x400). Larger files will obviously increase the size of the gadget snap and the resulting Ubuntu Core image. 50 | 51 | ### Replacement Plymouth theme 52 | 53 | The most flexible way to change the appearance of the Ubuntu Core splash screen is to install a replacement [Plymouth](https://wiki.ubuntu.com/Plymouth) theme. 54 | 55 | While Plymouth itself supports a variety of different splash plugins, Ubuntu Core’s implementation only supports its [Scripts](https://gitlab.freedesktop.org/plymouth/plymouth/-/tree/main/themes/script?ref_type=heads) plugin. This is the most flexible plugin as it provides its own feature-rich [scripting language](https://www.freedesktop.org/wiki/Software/Plymouth/Scripts/). 56 | 57 | A new theme must be placed within a `/splash/plymouth/themes/vendor` directory in the root of the Gadget snap: 58 | 59 | ``` 60 | $GADGET/splash/plymouth/themes/vendor/ 61 | ``` 62 | 63 | Pathnames specified in a custom Plymouth config file need to use the prefix `/run/mnt/gadget/splash/` rather than `/snap/gadget-snap/current/splash/` as the former is mounted in the _initramfs_ before Plymouth is starts, whereas the latter is not. 64 | 65 | It can also help to lower the kernel console logging verbosity by specifying `loglevel=3` (or lower) on the kernel command line. See [Customise the kernel command line](/reference/kernel-boot-parameter) for further details. 66 | 67 | A good custom Plymouth theme example for Ubuntu Core is its own default theme: 68 | [https://github.com/snapcore/core-splash](https://github.com/snapcore/core-splash) 69 | 70 | Note that the configuration file inside the `vendor/` directory must be named `vendor.plymouth`. Configuration inside will point to the script file. 71 | 72 | See [Building a gadget snap](/how-to-guides/image-creation/build-a-gadget-snap) for details on how to create a custom gadget snap. 73 | 74 | -------------------------------------------------------------------------------- /docs/how-to-guides/image-creation/add-console-conf.md: -------------------------------------------------------------------------------- 1 | # Add console-conf 2 | 3 | Console-conf is a text-based user-interface that can be optionally included in an Ubuntu Core image to provide interactive network and user configuration. 4 | 5 | ![Network connections](https://assets.ubuntu.com/v1/2017b744-8db3caab6834b5307574a8b6d7d6bb1f4a08230f_2_690x434.png) 6 | 7 | All pre-built testing images include console-conf, enabling those images to be configuration on first boot by connecting a device to a display and keyboard. User configuration requires an Ubuntu One account and registered SSH key. See [Use Ubuntu One for SSH ](/how-to-guides/manage-ubuntu-core/use-ubuntu-one-ssh) for details. 8 | 9 | The packages required to run console-conf are included in Ubuntu Core 22 images, but from Ubuntu Core 24 onwards, the console-conf has migrated to an [optional snap](https://snapcraft.io/console-conf). 10 | 11 | The console-conf snap can be added to your own images in two different ways: 12 | 13 | ## From within the model 14 | 15 | The console-conf snap can be added to the model declaration just like any other snap. Add the following to the json definition for your model: 16 | 17 | ```json 18 | { 19 | "name": "console-conf", 20 | "type": "app", 21 | "default-channel": "24/stable", 22 | "id": "ASctKBEHzVt3f1pbZLoekCvcigRjtuqw" 23 | }, 24 | ``` 25 | 26 | It's also included in the `ubuntu-core-24` [test image model declarations](https://github.com/snapcore/models), although it's marked at `optional` in these. Removing the `"presence": "optional"` line will trigger its inclusion when building your own versions of these models. 27 | 28 | See [Create a model assertion](/tutorials/build-your-first-image/create-a-model) for more details. 29 | 30 | ## Using the ubuntu-image command 31 | 32 | The [ubuntu-image](/) command is used to generate a bootable Ubuntu Core image from your source files. To build an image from the [ubuntu-core-24-amd64](https://raw.githubusercontent.com/snapcore/models/master/ubuntu-core-24-amd64.model) model assertion for the pre-built images, for example, use the following command: 33 | 34 | ```bash 35 | ubuntu-image snap ubuntu-core-24-amd64.model 36 | ``` 37 | 38 | The image generated by the above command will not launch console-conf, and instead, will take the user directly to a login prompt. This is because its model description marks the console-conf snap _optional_ and is consequently not included in the image. 39 | 40 | To force the inclusion of console-conf, or any other snap, use the `--snap` argument with `ubuntu-image`: 41 | 42 | ```bash 43 | ubuntu-image snap --snap console-conf ubuntu-core-24-amd64.model 44 | ``` 45 | 46 | The resultant image will boot to console-conf's onboarding menu. 47 | 48 | -------------------------------------------------------------------------------- /docs/how-to-guides/image-creation/add-custom-snaps.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-image-creation-add-custom-snaps)= 2 | # Add custom snaps 3 | 4 | An Ubuntu Core image is built using the [ubuntu-image](/how-to-guides/image-creation/use-ubuntu-image) command with a signed model assertion: 5 | 6 | ```bash 7 | ubuntu-image snap ubuntu-core-20-amd64.model 8 | ``` 9 | 10 | > See [Build your own Ubuntu Core image](/tutorials/build-your-first-image/index) for more details on the entire process. 11 | 12 | _ubuntu-image_ tool retrieves signed snaps with the given _snap-id_ in the model assertion from the store. To override these default snaps, first make sure the [model assertion](/reference/assertions/model.md#model-assertion-fields) has a grade of dangerous to allow non-store snaps to be included: 13 | 14 | ``` 15 | grade: dangerous 16 | ``` 17 | 18 | The `ubuntu-image` command can now build an image using locally sourced and built snaps, such as a custom gadget snap: 19 | 20 | ```bash 21 | ubuntu-image snap my-model.model --snap ./pc_20-0.4_amd64.snap 22 | ``` 23 | 24 | It is also possible to pre-download the snaps included in a model assertion, and include them manually with the `--snap` flag. This uses the locally cached copies and can save download and build time, which is useful for testing. 25 | 26 | You can now use the image to boot either real or virtual hardware. From within a running session on a custom image, you can run the pre-installed snap. Use `snap list` to see which snaps are installed: 27 | 28 | ```bash 29 | $ snap list 30 | Name Version Rev Tracking Publisher Notes 31 | core20 20250429 2582 latest/stable canonical✓ base 32 | pc 20-0.4 x1 - - gadget 33 | pc-kernel 5.4.0-214.234.1 2421 20/stable canonical✓ kernel 34 | snapd 2.68.4 24505 latest/stable canonical✓ snapd 35 | wormhole 0.16.0+2.g1bd72f3 509 latest/stable snapcrafters✪ - 36 | ``` 37 | 38 | The `snap model --assertion` command will show the read-only custom model assertion used to build the image: 39 | 40 | ``` 41 | $ snap model --assertion 42 | type: model 43 | authority-id: bJzr2XzZg6Qv6Z53HIeziXyxtn1XItIq 44 | series: 16 45 | brand-id: bJzr2XzZg6Qv6Z53HIeziXyxtn1XItIq 46 | model: ubuntu-core-20-amd64 47 | architecture: amd64 48 | base: core20 49 | grade: dangerous 50 | snaps: 51 | - 52 | default-channel: 20/stable 53 | id: UqFziVZDHLSyO3TqSWgNBoAdHbLI4dAH 54 | name: pc 55 | type: gadget 56 | - 57 | default-channel: 20/stable 58 | id: pYVQrBcKmBa0mZ4CCN7ExT6jH8rY1hza 59 | name: pc-kernel 60 | type: kernel 61 | - 62 | default-channel: latest/stable 63 | id: DLqre5XGLbDqg9jPtiAhRRjDuPVa5X1q 64 | name: core20 65 | type: base 66 | - 67 | default-channel: latest/stable 68 | id: PMrrV4ml8uWuEUDBT8dSGnKUYbevVhc4 69 | name: snapd 70 | type: snapd 71 | - 72 | default-channel: latest/stable 73 | id: hJmReLmgXSUj4SF7WhyTVRV6IzUa4QUZ 74 | name: htop 75 | type: app 76 | timestamp: 2020-11-17T13:09:51+00:00 77 | sign-key-sha3-384: 9aZR3b1U[...] 78 | ``` 79 | 80 | -------------------------------------------------------------------------------- /docs/how-to-guides/image-creation/index.md: -------------------------------------------------------------------------------- 1 | # Image creation 2 | 3 | Any device running Ubuntu Core is instantiated from an image. This image contains the kernel, an _init_ process, and a few essential tools. 4 | 5 | Customising and adding to Ubuntu Core images is a fundamental part of how Ubuntu Core operates, whether that's on an established platform, or by creating an image for a new platform. 6 | 7 | ## Modify and create images 8 | 9 | Create an image from the command line, optimise its boot speed, then change its configuration. 10 | 11 | - [Use ubuntu-image](use-ubuntu-image) 12 | - [Optimise boot speed](optimise-boot-speed) 13 | - [Add custom snaps](add-custom-snaps) 14 | - [Add a splash screen](add-a-splash-screen) 15 | - [Add console-conf](add-console-conf) 16 | 17 | ## Board enablement 18 | 19 | Pre-built images are available for testing a range of devices. See [Testing Platforms](/reference/testing-platforms) for further details. 20 | 21 | _Board enablement_, however, is the term we use for building an Ubuntu Core image for a new hardware platform, and there's a well established process for accomplishing this. 22 | 23 | - [Board enablement](board-enablement) 24 | - [Calculate partition sizes](calculate-partition-sizes) 25 | - [Build a gadget snap](build-a-gadget-snap) 26 | - [Build a kernel snap](build-a-kernel-snap) 27 | 28 | 29 | 30 | ```{toctree} 31 | :hidden: 32 | :titlesonly: 33 | :maxdepth: 2 34 | :glob: 35 | 36 | Use ubuntu-image 37 | Optimise boot speed 38 | Add custom snaps 39 | Add a splash screen 40 | Add console-conf 41 | Board enablement 42 | Calculate partition sizes 43 | Build a gadget snap 44 | Build a kernel snap 45 | -------------------------------------------------------------------------------- /docs/how-to-guides/image-creation/optimise-boot-speed.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-image-creation-optimise-boot-speed)= 2 | # Optimise boot speed 3 | 4 | When Ubuntu Core boots for the first time, a _seeding_ process installs an initial set of snaps and runs their respective hooks (see [Snaps in Ubuntu Core](/explanation/core-elements/snaps-in-ubuntu-core) for more details). 5 | 6 | Each installed snap needs to be verified and have their respective AppArmor and seccomp security profiles, systemd units, and mount points created. The time this takes is proportional to the number of asserted snaps being seeded, but installing many snaps can impact first boot speed. 7 | 8 | _Preseeding_ speeds up the seeding process by performing as many of these administrative tasks as possible in advance when an image is being created. 9 | 10 | ## Preseeding 11 | 12 | During deployment, _snapd_ still performs the _seeding_ process but it automatically skips any parts successfully completed during _pre-seeding_. 13 | 14 | ### Building a preseeded image 15 | 16 | During the process of [Image creation](/how-to-guides/image-creation/index), preseeded images are created with the same `ubuntu-image` tool, or the `snap prepare-image` command, with an additional `--preseed` argument. 17 | 18 | Pre-seeding requirements: 19 | * snapd 2.56 or newer, both on the host system (where the image is created) and in the resultant preseeded system. 20 | * Preseeding is supported in Ubuntu Core 20 onwards. 21 | * The same architecture on both the host and pre-seeded system (during pre-seeding, snapd from the target system is executed to perform seeding). 22 | * It's recommended that the kernel on the host should have the same AppArmor features as that of the target system. Differing AppArmor features will nullify the pre-created security profiles which will subsequently need to be recreated on first boot. 23 | 24 | Usage: 25 | 26 | ```bash 27 | snap prepare-image --preseed --preseed-sign-key= --channel=stable --snap=... 28 | ``` 29 | 30 | or with ubuntu-image: 31 | 32 | ```bash 33 | sudo ubuntu-image snap --preseed --preseed-sign-key= -i 8G --snap [...] 34 | ``` 35 | 36 | The `--preseed-sign-key` argument is optional and should be either the default GPG key or the key used to sign the model. 37 | 38 | A custom AppArmor features directory may be specified with `--apparmor-features-dir=...`. The target should be a snapshot of `sys/kernel/security/apparmor/features` from the target system. If not specified, the `sys/kernel/security/apparmor/features` from the host system will be used. 39 | 40 | On a new device, snaps are installed from the `ubuntu-seed` volume (see [Core elements](/explanation/core-elements/index)). On a classic system, this set of snaps to install is defined in `/var/lib/snapd/seed/seed.yaml`. 41 | 42 | ## Single boot installation 43 | 44 | During the installation of an Ubuntu Core system, the target device will undergo a reboot to finalize the installation process. If a system is preseeded, the installation can be completed without necessitating a system reboot. Note that this feature requires snapd version 2.62 and greater. 45 | 46 | -------------------------------------------------------------------------------- /docs/how-to-guides/index.md: -------------------------------------------------------------------------------- 1 | # How-to guides 2 | 3 | If you have a specific goal, but are already familiar with Ubuntu Core, our _How-to_ guides have more in-depth detail than our tutorials and can be applied to a broader set of applications. They'll help you achieve an end result but may require you to understand and adapt the steps to fit your specific requirements. 4 | 5 | ## How to use Ubuntu Core 6 | 7 | While Ubuntu Core is primarily intended for developers to build custom images tailored for their application and targeted hardware, this page is a great place to start after you’ve just installed pre-built Ubuntu Core images and want to learn a few of the basic principles quickly. 8 | 9 | - [Using Ubuntu Core](using-ubuntu-core) 10 | 11 | ## Image creation 12 | 13 | Any device running Ubuntu Core is instantiated from an image. This image contains little more than the kernel, an init process, and a few essential tools. On all but the earliest releases of Ubuntu Core, even the snapd daemon that manages snaps is itself installed via its own snap. 14 | 15 | - [Create images](image-creation/index) 16 | 17 | ## Manage Ubuntu Core 18 | 19 | Maintain and manage your Ubuntu Core systems, including recovery modes, system users, configuration options and kernel options. 20 | 21 | - [Manage Ubuntu Core](manage-ubuntu-core/index) 22 | 23 | ## Container deployment 24 | 25 | Ubuntu Core has been developed specifically to leverage the power of snap packages, with their autonomous upgrades and confined sandbox. But it can also be used to run and deploy Docker container images, either from the command line or embedded within an Ubuntu Core image. 26 | 27 | - [Deploy containers](container-deployment/index) 28 | 29 | 30 | 31 | ```{toctree} 32 | :hidden: 33 | :titlesonly: 34 | :maxdepth: 2 35 | :glob: 36 | 37 | Using Ubuntu Core 38 | Create images 39 | Manage Ubuntu Core 40 | Deploy containers 41 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/index.md: -------------------------------------------------------------------------------- 1 | # Manage-Ubuntu-Core 2 | 3 | ## Access and upgrades 4 | 5 | Run Ubuntu Core within a container, access a session using SSH and upgrade an older version of Ubuntu Core to a newer one. 6 | 7 | - [Test on QEMU](use-ubuntu-one-ssh) 8 | - [Use Ubuntu One SSH](use-ubuntu-one-ssh) 9 | - [Upgrade Ubuntu Core](upgrade-ubuntu-core) 10 | 11 | ## Recovery and problem solving 12 | 13 | While Ubuntu Core is a self-healing operating system, it can also boot into, or activate, various recovery modes. 14 | 15 | - [Create a recovery system from the API](create-a-recovery-system-from-the-api) 16 | - [Use a recovery mode](use-a-recovery-mode) 17 | - [Troubleshooting](troubleshooting) 18 | 19 | ## Customise the system 20 | 21 | Customise Ubuntu Core images and the running environment. 22 | 23 | - [Add a system user](add-a-system-user) 24 | - [Modify kernel options](modify-kernel-options) 25 | - [Set system time](set-system-time) 26 | - [Set system options](set-system-options) 27 | 28 | 29 | ```{toctree} 30 | :hidden: 31 | :titlesonly: 32 | :maxdepth: 2 33 | :glob: 34 | 35 | Test on QEMU 36 | Use Ubuntu One SSH 37 | Upgrade Ubuntu Core 38 | Set system options 39 | Use a recovery mode 40 | Add a system user 41 | Modify kernel options 42 | Create a recovery system from the API 43 | Set system time 44 | Troubleshooting 45 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/set-system-options.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-manage-ubuntu-core-set-system-options)= 2 | # Set system options 3 | 4 | Ubuntu Core supports a set of system-wide options that allow you to customise your snap and core environment. See [System options](https://snapcraft.io/docs/system-options) for which options are supported. 5 | 6 | As with [Configuration in snaps](https://snapcraft.io/docs/configuration-in-snaps), these options are changed with the `snap set` and `snap get` commands, but with a target of *system* instead of a specific snap: 7 | 8 | ``` bash 9 | snap set system some.option="some value" 10 | snap get system some.option 11 | ``` 12 | 13 | Configuration options can be unset by either passing their names to the unset command or by adding an exclamation mark (!) to the end of an option name: (from *snapd 2.41+*): 14 | 15 | ``` bash 16 | snap unset system some.option 17 | ``` 18 | or 19 | 20 | ``` 21 | snap set system some.option! 22 | ``` 23 | 24 | Typing `snap get system` outputs a top-level view of system-wide option categories which can be added as arguments to view their contents: 25 | 26 | ``` bash 27 | $ snap get system 28 | Key Value 29 | experimental {...} 30 | refresh {...} 31 | seed {...} 32 | $ snap get system experimental 33 | Key Value 34 | experimental.hotplug true 35 | experimental.layouts true 36 | ``` 37 | 38 | The entire set of system configuration options can be dumped as JSON by adding the -d option: 39 | 40 | ```bash 41 | $ snap get -d system 42 | { 43 | "experimental": { 44 | "hotplug": true, 45 | "layouts": true, 46 | "quota-groups": true 47 | }, 48 | "refresh": { 49 | "last": "2017-05-25T09:03:58.664837614+01:00", 50 | "retain": 2 51 | }, 52 | "seed": { 53 | "loaded": true 54 | }, 55 | "system": { 56 | "hostname": "neon", 57 | "network": {}, 58 | "timezone": "UTC" 59 | } 60 | } 61 | ``` 62 | 63 | See [Gadget snaps](https://snapcraft.io/docs/gadget-snap#heading--gadget) for details on how to create a default set of configuration values for a device. 64 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/set-system-time.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-manage-ubuntu-core-set-system-time)= 2 | # Set system time 3 | 4 | System time on an Ubuntu Core 20+ device is set and updated over several potential steps, depending on network access and the availability of a real-time clock (RTC). 5 | 6 | Regardless of how system time is set, it always moves forward monotonically and is never permitted to move backwards. 7 | 8 | ## System time update process 9 | 10 | The system time value and update process is tightly coupled to the [boots process](/explanation/core-elements/inside-ubuntu-core) and device capabilities. From a fresh boot of the device, the process for setting the time is as follows: 11 | 12 | 1. **initrd** 13 | When the device boots, _initrd_ first moves system time forward to match the time _initrd_ was built. 14 | - **snap-bootstrap** 15 | _snap-bootstrap_ is the main executable run during the early _initrd_ boot stage. It will itself move time forward to that of the most recent assertion it trusts, signed with Canonical's key. 16 | 1. **user-space** 17 | After the snap environment is re-executed and the boot process moves to user-space, systemd's _timesyncd_ will attempt to update the system time: 18 | - **on devices with an RTC** 19 | System time is moved forward to match that of the on-board RTC. 20 | - **on devices without an RTC** 21 | System time is taken from the modified file timestamp (mtime) of `/var/lib/systemd/timesync/clock` on the data partition (which may be encrypted). The timestamp for this file is updated periodically after a network connection has been established, and before the system reboots. 22 | 23 | When the network becomes available, the device will begin to use NTP to periodically update the system time. See [Network time synchronisation](#heading--ntp) below for more details. 24 | 25 | ## Current time 26 | 27 | The current system time and date can be retrieved with the `timedatectl` command: 28 | 29 | ```bash 30 | $ timedatectl 31 | Local time: Mon 2022-03-14 12:23:24 UTC 32 | Universal time: Mon 2022-03-14 12:23:24 UTC 33 | RTC time: Mon 2022-03-14 12:23:25 34 | Time zone: Etc/UTC (UTC, +0000) 35 | System clock synchronized: yes 36 | NTP service: active 37 | RTC in local TZ: no 38 | ``` 39 | 40 | ## Real-time clock (RTC) check 41 | 42 | If no real-time clock is present or accessible, the output from _timedatectl_ will include **`RTC time: n/a`**: 43 | 44 | ```bash 45 | $ timedatectl 46 | Local time: Mon 2022-03-14 12:23:24 UTC 47 | Universal time: Mon 2022-03-14 12:23:24 UTC 48 | RTC time: n/a 49 | Time zone: Etc/UTC (UTC, +0000) 50 | System clock synchronized: yes 51 | NTP service: active 52 | RTC in local TZ: no 53 | ``` 54 | 55 | ## Setting a timezone 56 | 57 | The timezone can be configured with the [system.timezone](https://snapcraft.io/docs/system-options#heading--timezone) system value: 58 | 59 | ``` 60 | $ snap set system system.timezone="America/Chicago" 61 | $ timedatectl | grep zone 62 | Time zone: America/Chicago (CDT, -0500) 63 | ``` 64 | 65 | ## Network time synchronisation 66 | 67 | By default, _timesyncd_ is configured to use the Network Time Protocol (NTP) for network time synchronisation as soon as the network becomes available. 68 | 69 | The NTP server and update frequency can be checked with _timedatectl timesync-status_: 70 | 71 | ``` 72 | $ timedatectl timesync-status 73 | Server: 91.189.89.198 (ntp.ubuntu.com) 74 | Poll interval: 4min 16s (min: 32s; max 34min 8s) 75 | Leap: normal 76 | Version: 4 77 | Stratum: 2 78 | Reference: 11FD22FB 79 | Precision: 1us (-23) 80 | Root distance: 30.234ms (max: 5s) 81 | Offset: +33.938ms 82 | Delay: 14.975ms 83 | Jitter: 37.394ms 84 | Packet count: 4 85 | Frequency: -14.982ppm 86 | ``` 87 | 88 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/troubleshooting.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-manage-ubuntu-core-troubleshooting)= 2 | # Troubleshooting 3 | 4 | Ubuntu Core runs on, and can be built for, a diverse and constantly evolving set of [platforms and devices](/reference/system-requirements). 5 | 6 | The majority of our users and developers experience very few issues, but any technology this complex and diverse will likely encounter some issues and incompatibilities. 7 | 8 | This page attempts to guide users to either an appropriate solution to their issues, or the correct forum/thread where they can get help. 9 | 10 | ## Ubuntu Core install error: TPM is in DA Lockout Mode 11 | 12 | Installing Ubuntu Core on a device with a TPM (such as an Intel NUC, or QEMU with emulated TPM) can sometimes result in a stalled installation and a **TPM is in DA Lockout Mode** error, as shown in the following example install log: 13 | 14 | ```no-highlight 15 | ubuntu snapd[15531]: handlers install.go:254: 16 | make system runnable 17 | ubuntu snapd[115531]: secboot_tpm.go:483: 18 | TPM provisioning error: the TPM is in DA lockout mode 19 | ubuntu snapd[115531]: taskrunner.go:271: 20 | [change 2 "Setup system for run mode" task] failed: 21 | cannot make system runnable: cannot seal the encryption keys: 22 | cannot provision TPM: the TPM is in DA lockout mode 23 | ubuntu snapd[15531]: secboot_tpm.go:483: TPM provisioning error: 24 | the TPM is in DA lockout mode 25 | ubuntu snapd[15531]: taskrunner.go:271: 26 | [change 2 "Setup system for run mode" task] failed: 27 | cannot make system runnable: 28 | cannot seal the encryption keys: 29 | cannot provision TPM: 30 | the TPM is in DA lockout mode 31 | ``` 32 | 33 | This error typically means the TPM has been locked to protect the system against potential dictionary attacks (DA) and the TPM needs to be cleared before the Ubuntu Core installation will proceed. 34 | 35 | To clear the TPM on hardware, boot a classic Ubuntu system (such as a live version of [Ubuntu 20.04 LTS](https://releases.ubuntu.com/20.04/) from USB storage) and run the following command from a terminal: 36 | 37 | ```bash 38 | echo 5 | sudo tee /sys/class/tpm/tpm0/ppi/request 39 | ``` 40 | 41 | To clear a software TPM, such as the [test-snapd-swtpm](https://snapcraft.io/test-snapd-swtpm) snap, remove it and re-install it again: 42 | 43 | ```bash 44 | snap remove test-snapd-swtpm --purge; snap install test-snapd-swtpm 45 | ``` 46 | 47 | Now reboot the problematic system and re-attempt the Ubuntu Core installation, which should continue without error. 48 | 49 | ## Console-conf shows no-ip 50 | 51 | During a [snap refresh](/explanation/refresh-control), _console-conf_ may display an `no-ip` message. 52 | 53 | Despite the _no-ip_ message, you should still be able to connect to the device using SSH if you actually know the IP. 54 | 55 | The [snap changes](https://snapcraft.io/docs/keeping-snaps-up-to-date#heading--changes) command will show that one or more snaps are being updated and the device may need to reboot. 56 | 57 | The solution to the _no-ip_ error is to simply wait for any updates to complete. 58 | 59 | ## Ubuntu Core boot asking for recovery key 60 | 61 | When using [Full Disk Encryption](/explanation/full-disk-encryption), a device’s Trusted Platform Module (TPM) stores the encryption keys necessary to decrypt and boot the device. 62 | 63 | If an encrypted drive is detected, but the TPM does not contain a valid key, the Ubuntu Core boot process will prompt for a recovery key. 64 | 65 | ```bash 66 | 🔐 Please enter the recovery key for disk /dev/disk/by-partuuid/c7f7971b: (press TAB for no echo) 67 | ``` 68 | 69 | To progress from this point, you will need to enter a previously retrieved recovery key for the device. 70 | 71 | See [Using recovery keys](/how-to-guides/manage-ubuntu-core/use-a-recovery-mode) for further details. 72 | 73 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/use-a-recovery-mode.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-manage-ubuntu-core-use-a-recovery-mode)= 2 | # Use a recovery mode 3 | 4 | Ubuntu Core is inherently robust. But if data corruption issues do occur, even on boot or data partitions, it can still access a recovery mode to help repair, restore or reinstall an impaired device. 5 | 6 | These recovery modes can be accessed in three different ways: 7 | 8 | - **[Boot into the system mode selection menu](#heading--chooser)** 9 | Start or reboot the device with the ‘1’ key held on a connected keyboard 10 | - **[Snap reboot](#heading-reboot)** 11 | Run `snap reboot` on the device with either `--recover` or `--install` arguments. 12 | - **[Snapd REST API](https://snapcraft.io/docs/snapd-api#heading--systems-get)** 13 | Use the REST API to call either the `recover`, `install`, `factory-reset` or `reboot` functions. 14 | 15 | Recovery modes are available on Ubuntu Core 20 and later. 16 | 17 | Device manufacturers may choose to implement alternative methods to access recovery functionality. These will be specific to those devices. 18 | 19 | See [Recovery modes](/explanation/recovery-modes) for more details on each supported recovery mode, what they do, and how they can be used. 20 | 21 | ## System mode selection menu 22 | 23 | To access the system mode selection menu, start or reboot the device with the ‘1’ key held on a connected keyboard. If the chooser fails to launch, try pressing _1_ repeatedly from boot. It needs to be captured by Ubuntu Core boot process. 24 | 25 | After the initial boot process completes, a status screen will appear showing “System mode selection triggered. Proceed to select one of the available systems and actions.” 26 | 27 | ![uc22-factory-reset|690x249](https://assets.ubuntu.com/v1/e67198a4-use-a-recovery-mode.png) 28 | 29 | The menu system requires that you tab or cursor to highlight your chosen option. Ensure ‘OK’ is highlighted and press Enter to continue, after which you'll be presented first with the recovery chooser and the option to either run normally, enter recovering mode, or reinstall. 30 | 31 | Selecting an option followed by ‘Confirm’ will reboot the device into the selected mode (see below). 32 | 33 | ## Recovery modes from snap reboot 34 | 35 | Alongside using `sudo snap reboot` to reboot the system, the following arguments can be added to select a recovery mode with or without an additional system label for the target system: 36 | 37 | - `--run` 38 | - `--install` 39 | - `--recover` 40 | - `--factory-reset` 41 | 42 | The _recover_ and _run_ modes are only available for the current system. 43 | 44 | When called without a system label, reboot will use the current system to enter the given mode. System labels are listed with the `snap recovery` command: 45 | 46 | ```bash 47 | $ sudo snap recovery 48 | Label Brand Model Notes 49 | 20201117 ubuntu-core-20-amd64 current 50 | ``` 51 | 52 | To reboot the above system into recover mode, for example, enter the following: 53 | 54 | ```bash 55 | $ sudo snap reboot --recover 20201117 56 | Broadcast message from root@ubuntu (Wed 2020-11-25 13:15:51 UTC): 57 | 58 | reboot scheduled to update the system 59 | The system is going down for reboot at Wed 2020-11-25 13:25:51 UTC! 60 | 61 | Reboot into "20201117" "recover" mode. 62 | ``` 63 | 64 | ## Using recovery keys 65 | 66 | When using [Full Disk Encryption](/explanation/full-disk-encryption), a device's Trusted Platform Module (TPM) seals the encryption keys necessary to decrypt and boot the device. 67 | 68 | These keys can be retrieved with the `snap recovery --show-keys` command: 69 | 70 | ```bash 71 | $ sudo snap recovery --show-keys 72 | recovery: 55055-39320-64491-48436-47667-15525-36879-32875 73 | ``` 74 | 75 | If a TPM becomes reinitialised or reconfigured, the TPM-sealed keys will be inaccessible and Ubuntu Core will not be able to decrypt and boot the device. 76 | 77 | During boot, Ubuntu Core will instead ask for the recovery key for specific encrypted partitions. The same keys recovered with `snap recovery --show-keys` can then be entered to restore the device: 78 | 79 | ```bash 80 | 🔐 Please enter the recovery key for disk /dev/disk/by-partuuid/c7f7971b: (press TAB for no echo) 81 | ``` 82 | After entering a valid key, Ubuntu Core will decrypt the device, proceed with the boot, and restore the TPM from the recovered key. The recovery keys will remain the same and do not need to be retrieved again. 83 | 84 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/use-ubuntu-one-ssh.md: -------------------------------------------------------------------------------- 1 | (how-to-guides-manage-ubuntu-core-use-ubuntu-one-ssh)= 2 | # Use Ubuntu One SSH 3 | 4 | By default, Ubuntu Core runs an [OpenSSH](https://help.ubuntu.com/community/SSH) server to enable secure remote connections to the device. 5 | 6 | Rather than requiring a password, the server is instead configured to authenticate connections with a public SSH key linked to the [Ubuntu One account](https://login.ubuntu.com/) used to configure the device. 7 | 8 | The process of creating and registering this key is described below. 9 | 10 | ## Ubuntu One setup 11 | 12 | 13 | [Ubuntu One](https://login.ubuntu.com/) is a single sign-on service for Ubuntu and affiliated projects. If you already have an account, make sure you're logged in. If you don't have an account, go to [https://login.ubuntu.com/](https://login.ubuntu.com/) and select the "I don’t have an Ubuntu One account" option. 14 | 15 | ![Ubuntu SSO Create Account](https://assets.ubuntu.com/v1/9ecc0252-sso-03.png) 16 | 17 | Fill out the form that appears. Your "full name" and "username" will be displayed next to any snaps you publish in the Snap Store, so you should choose appropriate branding. Use your organisation's name for both if you are publishing or generating Ubuntu Core images on their behalf. 18 | 19 | Ensure you read and accept the following: 20 | 21 | - [Ubuntu One terms of service](https://www.ubuntu.com/legal/terms-and-policies/terms-of-service) 22 | - [The data privacy policy](https://www.ubuntu.com/legal/dataprivacy) 23 | - [Canonical's SSO privacy notice](https://www.ubuntu.com/legal/dataprivacy/sso). 24 | 25 | Now select _Create account_. You will then receive an email asking you to verify your account. Click the verification link in the email and complete the reCAPTCHA challenge that follows. The account is now ready to be used. 26 | 27 | 28 | ## Generate the SSH key pair 29 | 30 | On Linux and macOS, the OpenSSH client package is usually pre-installed and this provides both the _ssh_ command for connecting to servers and the _ssh-keygen_ command used to generate an SSH public/private key pair. 31 | 32 | First make sure you have the required directory, and that it has the correct permissions: 33 | 34 | ```bash 35 | mkdir -p ~/.ssh 36 | chmod 700 ~/.ssh 37 | ``` 38 | 39 | Now run `ssh-keygen -t rsa` to generate the key pair. You will be asked for a filename and a passphrase. You may want to call the file something related to your Ubuntu Core device, such as `id_ubuntucore` in the example output below, but this is arbitrary. A passphrase is not necessary but can add an extra layer of security. 40 | 41 | This will generate a 2048-bit RSA key pair, which is secure enough for most use cases (you may optionally pass in the -b 4096 flag to the ssh-keygen command, to create a larger 4096-bit key). 42 | 43 | If you now look at the contents of the ~/.ssh directory, you will see both the private key and the public key (with a _.pub_ filename extension) as separate files: 44 | 45 | ```bash 46 | $ ls -1 ~/.ssh/id* 47 | ~/.ssh/id_ubuntucore 48 | ~/.ssh/id_ubuntucore.pub 49 | ``` 50 | 51 | ## Upload the public SSH key 52 | 53 | The contents of the _.pub_ file needs to be uploaded to the Ubuntu One account you want to associate with your Ubuntu Core device. 54 | 55 | 56 | To add a new key, first copy the contents of the _.pub_ public key generated in the previous step. This can be done by copying the output from `cat ~/.ssh/id_.pub` on the terminal, or by using a tool like [xclip](https://manpages.ubuntu.com/manpages/bionic/man1/xclip.1.html): 57 | 58 | ``` 59 | xclip ~/.ssh/id_ubuntucore.pub 60 | ``` 61 | 62 | The contents of the public key file need to pasted into the _Public SSH Key_ box beneath **Import new SSH key** on [https://login.ubuntu.com/ssh-keys](https://login.ubuntu.com/ssh-keys) (or select *SSH Keys* after login): 63 | 64 | ![Ubuntu One SSH entry](https://assets.ubuntu.com/v1/0a42eb8e-uc-ssh.png) 65 | 66 | Click on **Import SSH key** to complete the process. 67 | 68 | This SSH keys page lists all the keys associated with your account. It lets you delete those you no longer need, and add new keys. 69 | 70 | Every key listed here will be added to the `~/.ssh/authorized_keys` file on your Ubuntu Core devices when they are initialised, permitting SSH access to accounts with the private key. 71 | 72 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | (index)= 2 | 3 | # Ubuntu Core documentation 4 | 5 | **Ubuntu Core is Ubuntu engineered for embedded and IoT systems.** It's image-based and immutable, with every element confined within a separate sandbox. 6 | 7 | **It provides a deployment infrastructure for developers to deploy production images**, creating a minimal, secure, and transaction-based operating environment for your applications. 8 | 9 | **Ubuntu Core reduces the time needed to flash and provision images in production lines**, ensuring they're secure while delivering the desired user-experience to your users. 10 | 11 | **From Linux and maker space tinkerers, to the robotics, automotive and signage industries;** from a single device, to a deployment of thousands. From a tiny _SoC_ to a fleet of full-powered PCs. Ubuntu Core can handle it. 12 | 13 | ## In this documentation 14 | | | | 15 | |--|--| 16 | | [Tutorials](/tutorials/index)
Get started - a hands-on introduction to Ubuntu Core for new users
| [How-to guides](/how-to-guides/index)
Step-by-step guides covering key operations and common tasks | 17 | | [Explanation](/explanation/index)
Concepts - discussion and clarification of key topics | [Reference](/reference/index)
Technical information - specifications, APIs, architecture | 18 | 19 | * **Stores:** [Store overview](explanation/stores/store-overview) | [Brand accounts](explanation/stores/brand-accounts) | [Dedicated snap stores](explanation/stores/dedicated-snap-store) | [Store scoping](explanation/stores/store-scoping) 20 | * **Security:** [Full disk encryption](explanation/full-disk-encryption) | [Sandboxing](explanation/security-and-sandboxing) | [Use a recovery mode](how-to-guides/manage-ubuntu-core/use-a-recovery-mode) 21 | * **Management:** [Update control](explanation/refresh-control) | [Remodelling](explanation/remodelling) | [Upgrade Ubuntu Core](how-to-guides/manage-ubuntu-core/upgrade-ubuntu-core) 22 | * **Core elements:** [Introduction](explanation/core-elements/inside-ubuntu-core) | [Storage layout](explanation/core-elements/storage-layout) | [Snap in Ubuntu Core](explanation/core-elements/snaps-in-ubuntu-core) 23 | 24 | ## Project and community 25 | 26 | Ubuntu Core is a member of the Ubuntu family. It's an open source project that welcomes community projects, contributions, suggestions, fixes and constructive feedback. 27 | 28 | * [Community engagement commitment](explanation/community-engagement) 29 | * [Our Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct) 30 | * [How to get support](https://ubuntu.com/support/community-support) 31 | * [Join the Discourse forum](https://forum.snapcraft.io/c/device/10) 32 | * [Interactive chat on Matrix.org](https://matrix.to/#/#snapd:ubuntu.com) 33 | * [Product roadmap](https://snapcraft.io/docs/snapd-roadmap) 34 | 35 | Thinking about using Ubuntu Core for your next project? [Get in touch!](https://ubuntu.com/core/contact-us?product=core-overview) 36 | 37 | 38 | 39 | ```{toctree} 40 | :hidden: 41 | :titlesonly: 42 | :maxdepth: 2 43 | :glob: 44 | 45 | Tutorials 46 | How-to guides 47 | Reference 48 | Explanation 49 | How to contribute 50 | 51 | -------------------------------------------------------------------------------- /docs/reference/assertions/account-key.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-account-key)= 2 | # account-key 3 | 4 | The *account-key* [assertion](/reference/assertions/index) holds a public key belonging to an [account](/reference/assertions/account). 5 | 6 | This assertion is used to transmit key information between the [store](/explanation/stores/store-overview) and _snapd_, enabling the latter to validate assertions signed by the key owner. 7 | 8 | Alongside [account](/reference/assertions/account), [snap-declaration](/reference/assertions/snap-declaration) and [snap-revision](/reference/assertions/snap-revision) assertions, _account-key_ is bundled within the composite `.assert` file that accompanies a snap downloaded with the `snap download ` command. 9 | 10 | The `make-system-user` snap can is used to create a composite assertion file which includes all of the required assertions needed to trigger automatic creation of a user account via an inserted USB drive containing this file. See [make-system-user](/how-to-guides/manage-ubuntu-core/add-a-system-user) for more details. 11 | 12 | ## Account-key assertion fields 13 | 14 | The following fields can be used in an account-key user assertion: 15 | 16 | ```yaml 17 | type: account-key 18 | authority-id: 19 | revision: 20 | public-key-sha3-384: 21 | account-id: 22 | name: 23 | since: 24 | until: 25 | sign-key-sha3-384: # Encoded key id of signing key 26 | 27 | BODY: base64 encoded version prefixed public key packet 28 | 29 | # Encoded signature 30 | ``` 31 | 32 | The index for this assertion is `public-key-sha3-384`. The key is valid in the time interval specified by `since` and `until`, being valid forever if the optional`until` is undefined. 33 | 34 | - `public-key-sha3-384` is the SHA3-384 hash of the (decoded) body content. The body itself is a format version byte (`0x1` for now) followed by the public key packet itself. The version 1 public key packet is a constrained/normalised RFC4880 public key packet (v4, new header format, algorithm fixed to RSA, timestamp fixed as well). 35 | 36 | The digest of the public key (`public-key-sha3-384`) is used for the lookup of keys when verifying signatures: all assertions reference their signing key by providing this digest in a `sign-key-sha3-384` header. 37 | - `since` and `until` are required when a password is embedded within the assertion. They define the *from date* and the *to date* for they key’s validity. They need to be in UTC. 38 | 39 | In addition to the signature validation that's performed for all assertions, it's essential for the account-key assertion that the digest of the public key matches the assertion body. 40 | 41 | See [Assertion format](/reference/assertions/index.md#assertion-format) for more details on fields common to most assertions. 42 | 43 | ## Example assertion 44 | 45 | The following is Canonical's public key for the store: 46 | 47 | ```yaml 48 | type: account-key 49 | authority-id: canonical 50 | revision: 2 51 | public-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul 52 | account-id: canonical 53 | name: store 54 | since: 2016-04-01T00:00:00.0Z 55 | body-length: 717 56 | sign-key-sha3-384: -CvQKAwRQ5h3Ffn10FILJoEZUXOv6km9FwA80-Rcj-f-6jadQ89VRswHNiEB9Lxk 57 | 58 | AcbBTQRWhcGAARAA0KKYYQWuHOrsFVi4p4l7ZzSvX7kLgJFFeFgOkzdWKBTHEnsMKjl5mefFe9ji 59 | qe8NlmJdfY7BenP7XeBtwKp700H/t9lLrZbpTNAPHXYxEWFJp5bPqIcJYBZ+29oLVLN1Tc5X482R 60 | [...] 61 | ``` 62 | 63 | -------------------------------------------------------------------------------- /docs/reference/assertions/account.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-account)= 2 | # account 3 | 4 | The _account_ [assertion](/reference/assertions/index) ties the name for an account in the snap universe to its [store](/explanation/stores/store-overview) identifier and provides the authority's confidence in the name's validity. It is generated on user creation by the store where it's maintained while the account exists. 5 | 6 | Whenever a snap is installed, the account assertion linked to the owner of each snap is added to the system. To list account assertions present on a system, use the `snap known account` command. 7 | 8 | ## Account assertion fields 9 | 10 | The following fields can be used in an account assertion: 11 | 12 | ```yaml 13 | type: account 14 | authority-id: 15 | revision: 16 | account-id: 17 | display-name: 18 | username: 19 | validation: 20 | timestamp: 21 | sign-key-sha3-384: # Encoded key id of signing key 22 | 23 | # Encoded signature 24 | ``` 25 | 26 | The index for this assertion is the `account-id` and the fields are typically used in the following order: 27 | 28 | - `validation` when set to `certified` means that the authority is confident in that the display name accurately describes the owner of the account while `unproven` means that no checks have been performed. 29 | - `display-name` is a human-friendly name for the account-d, while username is an optional username associated with the account. 30 | - `timestamp` contains the UTC formatted date and time that 31 | 32 | See [Assertion format](/reference/assertions/index.md#assertion-format) for details on fields common to most assertions. 33 | 34 | ## Example assertion 35 | 36 | The following is a typical account assertion: 37 | 38 | ```yaml 39 | type: account 40 | authority-id: canonical 41 | revision: 11 42 | account-id: yBzXLuswoWh5b2gI8gxjziGARHLm64z 43 | display-name: VideoLAN 44 | timestamp: 2018-07-31T14:05:29.865155Z 45 | username: videolan 46 | validation: verified 47 | sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7Qi2NGSQ32EF2d4D0hqUel3m8ul 48 | 49 | AcLBUgQAAQoABgUCW2BsqgAAFCsQALkiVtqy0vwWbYXV+Pa3UrclKMDWjowgwdfvWfrbGkmBO13w 50 | moMQiY0uRsONZB5fovG0EhGgL7wSR6Z9OAOCuv48xJMrRWKFXtRT7/B45hOOXEihgp419BAdVAbl 51 | cUFh3ul/+EIQkSpXoRq9ChlA3QsbL6EszhD8ON4L58xauGotl/WbcwHqEoSGt9lURvSDTWWnW/rz 52 | 4IvKQsHF0paJ1YDcx+vNBZksaVBlltBswrquOqrA/lABenUuQdwRNYMckdyBb2rPHUG709luY1HA 53 | jmcRTl2++1yzVmhXV16I0HnOuajZAbr7fUL4PpyylMr1+gl9pulk9rbUkMCyyAYC5fd3QP2A+Aoc 54 | 52+mPD8PDkTnDpS91q4m3k9NW0j2 55 | ``` 56 | 57 | -------------------------------------------------------------------------------- /docs/reference/assertions/repair.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-repair)= 2 | # repair 3 | 4 | A _repair assertion_ is a unique type of [assertion](/reference/assertions/index) that is designed to be a **last resort feature** to repair unresponsive Ubuntu Core devices. Such devices are connected to a network but are otherwise beyond what can be fixed with a regular snapd refresh. 5 | 6 | Repair assertions: 7 | - can only be issued by Canonical 8 | - need to be requested by device manufacturers 9 | - are not directly available to customers and device manufacturers 10 | - are limited to specific models 11 | - require close collaboration and oversight from Canonical 12 | - are logged by devices to maintain a history of applied repair assertions 13 | - are publicly visible, including their payloads, to help prevent harmful operations 14 | 15 | A repair assertion will include a payload of _repair code_ to run via the assertion. This code should be as minimal as possible, and be just enough to make the regular snapd refresh update mechanism work again. 16 | 17 | Repair code also needs to be idempotent and typically capable of checking for whether an issue exists, or could occur at a later point, such as with a potential future update. 18 | 19 | The snap-repair process will retrieve and run repair assertions in sequence, executing one at a time. When running snap-repair after booting for the first time, a device will start from the beginning of the sequence. 20 | 21 | See [Repair capability](https://forum.snapcraft.io/t/repair-capability-emergency-fixes/311) on the Snapcraft forum for discussions related to the development of this feature. 22 | 23 | ## Repair assertion fields 24 | 25 | The following fields can be found in a repair assertion: 26 | 27 | ```yaml 28 | type: repair 29 | authority-id: 30 | brand-id: 31 | summary: 32 | architectures: 33 | series: 34 | models: 35 | timestamp: 36 | disables: 37 | body-length: 38 | repair-id: 39 | sign-key-sha3-384: 40 | ``` 41 | 42 | The primary key of the assertion is `(brand-id, repair-id)`. 43 | 44 | - `repair-id` is initially defined as an increasing number starting from 1.
To fetch a repair assertion in the sequence, _snap-repair_ will perform a GET on 45 | an HTTP repair URL that takes the same form as the assertion endpoints and the 46 | current version of the mechanism will consider one sequence with brand-id 47 | canonical, useful to repair any Core device. 48 | - `summary` is mandatory and should concisely document what the repair addresses. 49 | - `timestamp` is only for reference, signifying when the repair assertion was created. 50 | 51 | There are no `since` or `until` values because a device's system clock cannot be trusted. 52 | 53 | When optional series or architectures are omitted, all respective 54 | devices will be targeted. 55 | 56 | ## Example assertion 57 | 58 | The following is an example repair assertion used by the testing suite at Canonical: 59 | 60 | ```json 61 | { 62 | "headers": { 63 | "architectures": [ 64 | "amd64" 65 | ], 66 | "authority-id": "canonical", 67 | "body-length": "106", 68 | "brand-id": "canonical", 69 | "models": [ 70 | "vxj7EkYOlg15uAHRswTXIUpzWqO2sTBi/test-repairs-model" 71 | ], 72 | "repair-id": "1", 73 | "series": [ 74 | "16" 75 | ], 76 | "sign-key-sha3-384": "Jn3lCtSUzgoDedt5PDuPH4HDphA_ULFNmwyIZWVggp2D1jhkv16dnATSMDDrFXzj", 77 | "summary": "Repair assertion for production test device that just echos", 78 | "timestamp": "2019-10-02T10:30:00Z", 79 | "type": "repair" 80 | } 81 | } 82 | ``` 83 | 84 | -------------------------------------------------------------------------------- /docs/reference/assertions/serial.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-serial)= 2 | # serial 3 | 4 | The _serial_ [assertion](/reference/assertions/index) is a statement that binds a device identity to the device's public key. 5 | 6 | Every Ubuntu Core device belongs to a particular model, as defined by its [model assertion](/reference/assertions/model). 7 | 8 | Each device also has a unique device identity and the ability to _prove that identity_ with cryptographic keys. The precise implementation of this cryptography may vary from device to device, based on the hardware and software capabilities, which is described as part of the [gadget snap](/reference/gadget-snap-format). 9 | 10 | ## Fields 11 | 12 | The following fields can be used in an serial assertion: 13 | 14 | ```yaml 15 | type: serial 16 | authority-id: 17 | revision: 18 | brand-id: 19 | model : 20 | serial: 21 | device-key: 22 | device-key-sha3-384: 23 | timestamp: 24 | sign-key-sha3-384: # Encoded key id of signing key 25 | 26 | BODY: map of hardware constraints/details # expected to be YAML 27 | 28 | # Encoded signature 29 | ``` 30 | 31 | The index is the tuple \<`brand-id`, `model`, `serial`\>, with `serial` being the unique identifier for a device. `brand-id` and `model` must match those used by the device's [model assertion](/reference/assertions/model). 32 | 33 | - `serial` is crucial. In the context of the _model_, this this defines the unique identifier for a single device. The [brand](/explanation/stores/dedicated-snap-stores) should never assign the same serial to more than one device of the same model. 34 | 35 | - `device-key` is also unique to each device, and takes the same format used by the key in the [account-key assertion](/reference/assertions/account-key). 36 | 37 | The device key might change over time, in a controlled fashion, but at any given time there is only one device key per device. 38 | - `device-key-sha3-384` is the digest of the public key and should also be provided. 39 | 40 | - `BODY` (optional) contains device details in YAML format. 41 | 42 | This assertion must then be signed by the brand. See [Assertion format](/reference/assertions/index) for more details on fields common to most assertions. 43 | 44 | ## Example assertion 45 | 46 | This example was extracted from a kvm Ubuntu Core instance with `sudo snap known serial`: 47 | 48 | ```yaml 49 | type: serial 50 | authority-id: canonical 51 | brand-id: canonical 52 | model: pc-amd64 53 | serial: 03961d5d-26e5-443f-838d-6db046126bea 54 | device-key: 55 | AcbBTQRWhcGAARAA0y/BXkBJjPOl24qPKOZWy7H+6+piDPtyKIGfU9TDDrFjFnv3R8EMTz1WNW8d 56 | 5nLR8gjDXNh3z7dLIbSPeC54bvQ7LlaO2VYICGdzHT5+68Rod9h5NYdTKgaWDyHdm2K1v2oOzmMF 57 | Z+MmL15TvP9lX1U8OIVkmHhCO7FeDGsPlsTX2Wz++SrOqG4PsvpYsaYUTHE+oZ+Eo8oySW/OxTmp 58 | rQIEUoDEWNbFR5/+33tHRDxKSjeErCVuVetZxlZW/gpCx5tmCyAcBgKoEKsPqrgzW4wUAONaSOGc 59 | Zuo35DxwqeGHOx3C118rYrGvqA2mCn3fFz/mqnciK3JzLemLjw4HyVd1DyaKUgGjR6VYBcadL72n 60 | YN6gPiMMmlaAPtkdFIkqIp1OpvUFEEEHwNI88klM/N8+t3JE8cFpG6n4WBdHUAwtMmmVxXm5IsM3 61 | uNwrZdIBUu4WOAAgu2ZioeHLIQlDGw6dvVTaK+dTe0EXo5j+mH5DFnn0W1L7IAj6rX8HdiM5X5fP 62 | 4kwiezSfYXJgctdi0gizdGB7wcH0/JynaXA/tI3fEVDu45X7dA/XnCEzYkBxpidNfDkmXxSWt5N/ 63 | NMuHZqqmNHNfLeKAo1yQ/SH702nth6vJYJaIX4Pgv5cVrX5L429U5SHV+8HaE0lPCfFo/rKRJa9i 64 | rvnJ5OGR4TeRTLsAEQEAAQ== 65 | device-key-sha3-384: _4U3nReiiIMIaHcl6zSdRzcu75Tz37FW8b7NHhxXjNaPaZzyGooMFqur0EFCLS6V 66 | timestamp: 2016-11-08T18:16:12.977431Z 67 | sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul 68 | 69 | AcLBUgQAAQoABgUCWCIWcgAARegQAB4/UsBpzqLOYOpmR/j9BX5XNyEWxOWgFg5QLaY+0bIz/nbU 70 | avFH4EwV7YKQxX5nGmt7vfFoUPsRrWO4E6RtXQ1x5kYr8sSltLIYEkUjHO7sqB6gzomQYkMnS2fI 71 | xOZwJs9ev2sCnqr9pwPC8MDS5KW5iwXYvdBP1CIwNfQO48Ys8SC9MdYH0t3DbnuG/w+EceOIyI3o 72 | ilkB427DiueGwlBpjNRSE4B8cvglXW9rcYW72bnNs1DSnCq8tNHHybBtOYm/Y/jmk7UGXwqYUGQQ 73 | Iwu1W+SgloJdXLLgM80bPzLy+cYiIe1W1FSMzVdOforTkG5mVFHTL/0l4eceWequfcxU3DW9ggcN 74 | YJx8MPW9ab5gPibx8FeVb6cMWEvm8S7wXIRSff/bkHMhpjAagp+A6dyYsuUwPXFxCvHSpT0vUwFS 75 | CCPHkPUwj54GjKAGEkKMx+s0psQ3V+fcZgW5TBxk/+J83S/+6AiQ06W8rkabWCRyl2fX81vMBynQ 76 | nu147uRGWTXfa31Mys9lAGNHMtEcMmA106f2XfATqNK99GlIIjOxqEe5zH3j51JtY+5kyJd9cqvl 77 | Pb0rZnPySeGxnV4Q2403As67AJrIExRrcrK2yXZjEW3G2zTsFNzBSSZr0U8id1UJ/EZLB/em2EHw 78 | D2FXTwfDiwGroHYUFAEu1DkHx7Sy 79 | ``` 80 | 81 | -------------------------------------------------------------------------------- /docs/reference/assertions/snap-build.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-snap-build)= 2 | # snap-build 3 | 4 | 5 | The snap-build assertion defines the basic properties of a snap at the time it was built by the developer. These are assertions are created and uploaded to the store with the command `snapcraft sign-build `. 6 | 7 | Currently, the only usage of this assertion is to provide traceability between publisher and snap. It is not checked by snapd or other parts of the system. 8 | 9 | The format is as follows: 10 | 11 | ```yaml 12 | type: snap-build 13 | authority-id: 14 | revision: 15 | snap-sha3-384: 16 | snap-id: 17 | grade: 18 | snap-size: 19 | timestamp: 20 | sign-key-sha3-384: # Encoded key id of signing key 21 | 22 | # Encoded signature 23 | ``` 24 | 25 | The index is the digest of the snap blob, `snap-sha3-384`. `grade` tells us whether the snap can be published to the candidate or stable channel (if stable) or not (if devel). 26 | 27 | An example for this assertion: 28 | 29 | ```yaml 30 | type: snap-build 31 | authority-id: ouMZ22pMaY5EVwoLozfjM4fR31bko4yj 32 | snap-sha3-384: UFLajZv9twDGKvqorGn7ddN_hMPuq0DNlh24VGblYQZSM7EzcLRKGdxdigi6DUti 33 | developer-id: ouMZ22pMaY5EVwoLozfjM4fR31bko4yj 34 | grade: stable 35 | snap-id: xoHNzwxGwQ2D4rSZwI3DKsjtRuy9saeI 36 | snap-size: 6840320 37 | timestamp: 2017-02-20T12:50:12+01:00 38 | sign-key-sha3-384: kKl-kgxTJSR-wm5OT5M-gVxo4zv0Y19AAloJE4dq7C0QlbPsdbof0G5g0lCpg0J_ 39 | 40 | AcLBXAQAAQoABgUCWKrX9AAKCRCuieT/1PiUiBwuD/0fEfBS1IZ62PS0kyRbUDxBEPN3gzgw6mhX 41 | DaB5bxz2xJ/qQEGfoZdddH7Q45K1lr5pPVL99P2WFwFmdCvWsrcYuK2MZnzwhovD3oPATcFxTnj3 42 | ZttXwW7hDVokdvOwLdyvEaBkuyyO6awidzxFISsqgiaK2DzAwzA6aSXIOaYGDAfALm/YdzvZsfrk 43 | +jTswZy/jbWlZf0z8C0bQGa/euJAWtzRScucHEK4RxM2qq7hok6AIl9xDBalfZOdlyB01ReM+68z 44 | KldXoDQlyvMygx63HTXkmirJjWAUiiQ+5rJz9/zn8j84gT+R7qBgWBRd0l9KCZjalEDlXaNjfau3 45 | NZHJ3FgGqZLx7vkGpqExJEAEDcyiMHj7XV5WSsKTgtTSkE4LvicICYiy6IhgiQ/+2wADMnTRQY0U 46 | 2GuN3amiEQ9873aohlmmnJUUxpchNZHxgUSC0nUprmSgEUBNi4giRrD8Gs5Mji2cy9qk7yqxkXu0 47 | NjagDzsTHYPo2XlV93cyNJwPbjlshmS0NA/wAJRiwq0AkqgCaZweHuriJeewFnfAg2wyCz1nfh9X 48 | XWJSX+DR6tLnkZ1evRG9g0a8LzBtKwlrq7+sMAvxglAQlw3JZG/4yRw4NTZJQ4t4+9Eybzkf587f 49 | SDhf+j3c0JNUgb9o8isewL2+LLcvgM8tTSAmRxYqTw== 50 | ``` 51 | 52 | -------------------------------------------------------------------------------- /docs/reference/assertions/snap-resource-pair.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-snap-resource-pair)= 2 | # snap-resource-pair 3 | 4 | The `snap-resource-pair` assertion is one of two assertions used by [components](https://snapcraft.io/docs/components), the other being [snap-resource-revision](/reference/assertions/snap-resource-revision). 5 | 6 | This assertion defines the relationship between a [snap revision](https://snapcraft.io/docs/revisions) and a component revision. This assertion states that the given snap revision and component revision may be installed alongside each other. 7 | 8 | The primary keys are `snap-id`, `snap-revision`, `resource-name`, `resource-revision`, and `provenance`. Note that `provenance` is only relevant if the snap itself defines a provenance. 9 | 10 | ## Assertion fields 11 | 12 | ```yaml 13 | type: snap-resource-pair 14 | authority-id: canonical| 15 | snap-id: 16 | resource-name: 17 | resource-revision: 18 | snap-revision: 19 | provenance: # optional, like for snap revisions 20 | developer-id: 21 | ``` 22 | 23 | -------------------------------------------------------------------------------- /docs/reference/assertions/snap-resource-revision.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-snap-resource-revision)= 2 | # snap-resource-revision 3 | 4 | The `snap-resource-revision` assertion is one of two assertions used by [components](https://snapcraft.io/docs/components), the other being [snap-resource-pair](/reference/assertions/snap-resource-pair). 5 | 6 | This assertion performs a similar function to the [snap-revision](/reference/assertions/snap-revision) assertion, but for components. It describes a component revision and provides the metadata needed to verify that a component blob is a specific revision. 7 | 8 | The primary keys are `snap-id`, `resource-name`, `resource-sha3-384`, and `provenance`. Note that `provenance` is only relevant if the snap itself defines a provenance. 9 | 10 | 11 | ## Assertion fields 12 | 13 | ```yaml 14 | type: snap-resource-revision 15 | authority-id: canonical| 16 | snap-id: 17 | resource-name: 18 | resource-sha3-384: 19 | provenance: # optional, like for snap revisions 20 | resource-revision: 21 | resource-size: 22 | developer-id: 23 | ``` 24 | 25 | -------------------------------------------------------------------------------- /docs/reference/assertions/snap-revision.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-snap-revision)= 2 | # snap-revision 3 | 4 | The _snap-revision_ [assertion](/reference/assertions/index) is a statement by the [store](/explanation/stores/store-overview) acknowledging the receipt of a snap build and labelling it with a snap [revision](https://snapcraft.io/docs/glossary#heading--revision). 5 | 6 | Alongside [account](/reference/assertions/account), [snap-declaration](/reference/assertions/snap-declaration) and [account-key-assertion](/reference/assertions/account-key) assertions, snap-revision_ is bundled within the composite `.assert` file that accompanies a snap downloaded with the `snap download ` command. 7 | 8 | ## Snap-revision assertion fields 9 | 10 | The assertion format is as follows: 11 | 12 | ```yaml 13 | type: snap-revision 14 | authority-id: 15 | snap-sha3-384: 16 | developer-id: 17 | snap-id: 18 | snap-revision: 19 | snap-size: 20 | timestamp: 21 | sign-key-sha3-384: # Encoded key id of signing key 22 | 23 | # Encoded signature 24 | ``` 25 | 26 | The index is the digest of the snap blob, `snap-sha3-384`. The store returns the `revision` assigned to the uploaded snap along other data. 27 | 28 | See [Assertion format](/reference/assertions/index.md#assertion-format) for more details on fields common to most assertions. 29 | 30 | ## Example assertion 31 | 32 | The following is an example `snap-revision` assertion: 33 | 34 | ```yaml 35 | type: snap-revision 36 | authority-id: canonical 37 | snap-sha3-384: F5gwZqB3EBPQ62fhu2CL65TPNdyLbxCVdsxEReYrnp5sNu2z2BXAjdk_BRfUKJgV 38 | developer-id: canonical 39 | snap-id: RmBXKl6HO6YOC2DE4G2q1JzWImC04EUy 40 | snap-revision: 44 41 | snap-size: 5234688 42 | timestamp: 2016-11-03T10:39:25.624109Z 43 | sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul 44 | 45 | AcLBUgQAAQoABgUCWBsT3QAA/JgQAH+XrRnxFLFzCHVXF5B6yKbj1e5M2YTUXZ3XLHp+eGU93t+h 46 | 54UxBwgSKX/Wb1MliOpWG7IuhIw0WsUzM/Ynq5Ixhmf/f8E5p7hP9JJU6+UJaJCnnLtmRLG3x6Y7 47 | YmYIPGEvhn8VuznuTCyqyqRdiiu3U1aKecMyKRdKQvfDdJV4XveTuWlCuHjHplJ/apApyZQDCA/O 48 | Qr6grtz/Ud1bR9ThR0KISTuRhE/2qFOuNCVTHU2lFYGrECF0vJYo42tW2R85ZdsOpdVngAMUAJOZ 49 | REZKML9cgnJqIDwuZ4DNl+684p71+mNeQtbg2608F8fiK2jFJa8mHY5kxhzFGrIPVXEVmPTRlc0Q 50 | dPdViCOeg4jOuCybKQ/DrzE7Vjqhgl6UbKX2JtLbSxwBuB65YijCTVbqZD+u58ek9N9Z6ZKrJz2o 51 | HXq6RZqTpkCagV3FIxRRGhBDWQCePY4tRNEj9+3u31Af9daswRlmrFXwWDf46KPKx+fJ9jPECknO 52 | s+jQ5ij3fpMfWOzceHHLhIDm9Wj7sypD+63v4KDaXzQ+8dM/acMraNAJHRvCOr7bvFz9j7OEqr7y 53 | /6/QMZdkeYO94e1OPB5e+Dya95oCVqJhf05BAIKOn933EjGT3Vnm7HT+EzCvLUbbjMPlJ6ZyNnp/ 54 | lE+8N8EQWmdLC+OwJRNHgucjvcaR 55 | ``` 56 | -------------------------------------------------------------------------------- /docs/reference/assertions/store.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-store)= 2 | # store 3 | 4 | The store assertion defines the configuration needed to connect a device to a store. The `friendly-stores` list enables the creation of trust relationships to other stores. 5 | 6 | ```yaml 7 | type: store 8 | authority-id: 9 | store: 10 | friendly-stores: # Their snaps will be made available to the store. 11 | operator-id: 12 | url: 13 | location: 14 | timestamp: 15 | sign-key-sha3-384: # Encoded key id of signing key 16 | 17 | # Encoded signature 18 | ``` 19 | 20 | The following is a complete example store assertion: 21 | 22 | ```yaml 23 | type: store 24 | authority-id: canonical 25 | store: UDifxuoKrcYe65492eDA 26 | friendly-stores: 27 | - example-store 28 | operator-id: canonical 29 | timestamp: 2021-06-16T10:13:54.711843Z 30 | sign-key-sha3-384: BWDEoaqyr25nF5SNCvEv2v7QnM9QsfCc0PBMYD_i2NGSQ32EF2d4D0hqUel3m8ul 31 | 32 | AcLBUgQAAQoABgUCYMnO4gAAl54QAEEHC9DaViDa7a2jP/sTHy7GIieUSZ+He4zhVIJ40MTL4RFl 33 | CXsicJnvBN8NkPj9Smfheab1k4/C5zHXWfQOtPcpNhnV8w8BULzygemYrLtRkuW2I8NU2uXziARU 34 | VdqtzLP8xvb1c1QJ81dOWAuNLGoaD3GX3jV0e65oz8Fxas87YYyS537TKGHCjJ9t7SCpdLfGBRl4 35 | hvnCAk2e5fYHXKK9BjZ1SgQ6y32OXWsxlH0lMiTAf9ILp74AP6KQctsn7W936xavJl+76IaTIWee 36 | xx+I02LW9hUpr8wSVhk+Kjq7XgIQNMimVAIDsUBz/kYQ2xtUVtD2vmpvDceF3N32ZX9Lm16xBQTo 37 | 7ZOO8JBFdv7SY4qe2Xssqi387UrEuMzBF/sPtsHiT6ByOy6xGLNVib5pahb2/7k/Mg+sMuREY/n+ 38 | 3rWsFLW1wh/3iDAXeQnt5crkXYsdsIjsxE8ULW/zt16CJFUfaqcRf7ta0LeIyhm5IYa5vtcC2wOy 39 | nMGfZJ6Xgr/U4MYHysEifFttUisttvI87HKQEfJU96g0rHPFt/x+PU2tUYz0+2O7y/wjRGXemOaq 40 | xpG0hzLc6zTR32rqx3fO3H+0031xVozUNJxvkk6sg2omCGY9yaTwyKn6QvXs0FI48JqEKr9cdV7v 41 | rbT86NActIgyBDX8ofx/Vz3kvuDi 42 | ``` 43 | -------------------------------------------------------------------------------- /docs/reference/assertions/validation-set.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-validation-set)= 2 | # validation-set 3 | 4 | A validation set is an assertion that lists specific snaps that are either required to be installed together or are permitted to be installed together on a device or system. 5 | 6 | One or more validation sets can be used to ensure only specific snaps are installed, and optionally, only specific snaps at fixed revisions. They can help a set of interdependent snaps maintain their testing and certification integrity, as well as help orchestrate their updates. But they can equally be used to simplify dependency deployment and to help manage devices. 7 | 8 | For more information on its usage with snaps, see the [Snapcraft documentation](https://snapcraft.io/docs/validation-sets). 9 | 10 | The validation-set assertion format is as follows: 11 | 12 | ```yaml 13 | type: validation-set 14 | authority-id: 15 | series: 16 | account-id: 17 | name: 18 | revision: 19 | sequence: 20 | snaps: 21 | - name: 22 | id: 23 | presence: [required|optional|invalid] # Optional, defaults to required. 24 | revision: # The revision of the snap. Optional. 25 | 26 | timestamp: 27 | sign-key-sha3-384: # Encoded key id of signing key 28 | 29 | # Encoded signature 30 | ``` 31 | 32 | The above template validation set assertion needs to be populated with the details of the snaps you wish to include in the set. These are listed beneath the `snaps:` section, and each snap can use the following fields: 33 | 34 | - **`name`** (*required*) 35 | The name of the snap, as you find on the store or in _snap search_. 36 | - **`id`** (*optional*) 37 | The unique snap-id of the snap (see _snap info \_ ). 38 | Defaults to the snap-id of the named snap. 39 | - **`presence`** (*optional*) 40 | Can be either `required`, `optional` or `invalid`. 41 | `required` snaps need to be installed, `optional` snaps are permitted to be installed and `invalid` snaps explicitly must not be installed. 42 | Defaults to _required_. 43 | - **`revision`** (*optional*) 44 | Specifies which revision of the snap needs to be installed. 45 | 46 | An example of this type: 47 | 48 | ```yaml 49 | type: validation-set 50 | authority-id: example-account 51 | series: 16 52 | account-id: example-account 53 | name: testset1 54 | sequence: 1 55 | snaps: 56 | - 57 | id: buPKUD3TKqCOgLEjjHx5kSiCpIs5cMuQ 58 | name: hello-world 59 | timestamp: 2021-12-14T13:56:22Z 60 | sign-key-sha3-384: b-mO5Wolu7bgpmXmRyICa3b2Vvcpi-uX5AIenSiwTi_6RKhTAOqwe4W3vNtb6O2y 61 | 62 | AcLBcwQAAQoAHRYhBFwZ6nBkn0/POY1BgvtdqilNkrIXBQJhuKKGAAoJEPtdqilNkrIXcfwQAKbm 63 | P8XBkYyG9TWDRuh+A9YYndY6m/vjfUbJP7psau3JNheW10Hm6cl8pdhNaktC/neKClFEpXp1rgN5 64 | RtfenH/FsaYH176e+104171bHFL29GfGi1Aewl2Hc50XvzMcNPa4L91uhCDGzXpEBsYNwMxvDnWs 65 | 1Ze9zvedGF5JcWX97HOnyY3T4nYRQKkt3OFTyOJpuGfJOXGL+9mhkaunmcKab89g0jgnLt1o6CYE 66 | vbHjbE5ayR6bV4Ily3Z6ffUkjJRvGmR4UinutXe0v5M6oFeYim/GbgVT2ciLrzvJDklRQlvKQfyG 67 | OosR8dSVrIaTl0Xo+qfCGQzdjol3oD6gFVZJ9mhE6KjJsV7MJFCVU9WcAH697Rh4JVzmaQv44AOy 68 | 4btDzUmWvaA8fATBhtZmA9kk3zhxB04ZLSojIuZ9zES5b+OwA4QqrGjsPAqBkpQeQ6GhqPC6qEZK 69 | HnSGOxUpeAkYW+L0oB6RA5KtGMSuDNbtWyWrIhwWiOBaZceCuZUFo4Oost1QbxGrKXa97IHZKSLv 70 | fRkUz2cgVhuBVZS8Z6eecCIDqdGnzWOW4z0h35QQvzEmqhMHHrtJFGF43V7RO80puT4B3m55aTkt 71 | 1QE72e3BsVUEa3sx/lMfVX7dSNoJkDtSkw0Ft3teqNMkhPbEBkobjrzTzX9xwJ+mFT9NPSPH 72 | 73 | ``` 74 | 75 | -------------------------------------------------------------------------------- /docs/reference/assertions/validation.md: -------------------------------------------------------------------------------- 1 | (reference-assertions-validation)= 2 | # validation 3 | 4 | The _validation_ [assertion](/reference/assertions/index) declares that a certain [revision](https://snapcraft.io/docs/glossary#heading--revision) for a _snap that is gated by another snap_ has been validated for a given [series](https://snapcraft.io/docs/glossary#heading--series). It is closely related to the [snap-declaration](/reference/assertions/snap-declaration) assertion. 5 | 6 | ## Validation assertion fields 7 | 8 | The following fields can be used in a validation assertion: 9 | 10 | ```yaml 11 | type: validation 12 | authority-id: 13 | revision: 14 | series: 15 | snap-id: 16 | approved-snap-id: 17 | approved-snap-revision: 18 | timestamp: 19 | revoked: 20 | sign-key-sha3-384: # Encoded key id of signing key 21 | 22 | # Encoded signature 23 | ``` 24 | 25 | The index is the tuple \<`series`, `snap-id`, `approved-snap-id`, `approved-snap-revision`\>. 26 | 27 | This assertion indicates that refreshing to revision number `revision` of snap `approved-snap-id`, for `series`, has been approved by `authority-id`, given that `snap-id` the snap that was gating the update also has `authority-id` as the owner. 28 | 29 | The `approved-snap-id` must be part of the [refresh-control](/explanation/refresh-control) list in the [snap-declaration assertion](/reference/assertions/snap-declaration) of `snap-id` for this to be enforced. 30 | 31 | This means the recommended revision for `approved-snap-id` in a system that has `snap-id` installed is the one in the `revision` header. There will be no automatic installation of newer revisions until a validation with a newer revision is released by the store. Note however that this does not forbid a forced update by the device owner. 32 | 33 | The validation can be revoked by using the optional flag `revoked`. 34 | 35 | See [Assertion format](/reference/assertions/index.md#assertion-format) for more details on fields common to most assertions. 36 | 37 | ## Example assertion 38 | 39 | The following is an example validation assertion: 40 | 41 | ```yaml 42 | type: validation 43 | authority-id: canonical 44 | revision: 1 45 | series: 16 46 | snap-id: kkOOPWIl0sF7FoSA0KRTt83b1eoynkBa 47 | approved-snap-id: JIpOmfrI0JpaN3uNQQgNv5x3fW06nOYX 48 | approved-snap-revision: 37 49 | timestamp: 2017-02-20T10:23:51+00:00 50 | sign-key-sha3-384: C9mhxTpowHTXM3HOwgg3ZCX-WD05CczlNMdrCBbl2l0d4J_CcjYBS8NQpI-TtQlL 51 | 52 | AcLBXAQAAQoABgUCWKrI2QAKCRC03QWqtcJXZRFbEACDcCy15wPNpjcJyFYEt05A4WWzGPQMlC09 53 | 1lv62WAancrRaenLOi3xmeIPgsuPk9xKgrn16dBlytCK5GUHiHsafR+34mt/ridaVSKY5zCIkvcJ 54 | mgIH3jMB1RZiY2gtlxXD14G+nK67PKvM6BBfMdBB9ItLAdh5LM3ycbE/8ZqY7aYuTLKfOIPYGjUY 55 | 2rRlOaCggeXsru9wbnNwCwGBHZ9ltBgsISZQiSMGnH38OMNgjNOQy0PIB+elmYLEoTKXc+qU1x5w 56 | /R8cwUzWwcd56Ty/WpGdAfBrpO4/afFgVtGrixEWtVigIoIigPb7wytmQYcnl/Y0bQMVNZiYFQdF 57 | tZ9MGGTzA/ieRrjJHOQEj+VfDA4rHU2vUTGlZtseukhGNhSNgI52zhDyynhB/Hxy1t0rJ8eJju2a 58 | G27p2GuJvGrxfjxcge47LZ0WJaKe9R82/AsrFLlnJ4d29K0RUPnYohwlDwWTAOTE2SAz6/kIRNIv 59 | sOuHdIXIMarsbbRIG1kC++Rl/XI9jWvoM++fT1kHCjXgKfi+CELo8YcOKHPbjWSd7DiAmSnR5I6f 60 | ovydzkMPTzzbsxyKePQHicKiqPs4dSfcEnPIGTpvgpGE4WEI3zYGYmsGgFOJqEnuy0IvVRCtJXU4 61 | yk/p3Jqwss3W0YbfypCWrvMBxho1mN5SRhaQv3r+kw== 62 | ``` 63 | 64 | -------------------------------------------------------------------------------- /docs/reference/index.md: -------------------------------------------------------------------------------- 1 | # Reference 2 | 3 | Our *Reference section* is for when you need to know which options can be used, what functions the API supports, which rescue modes are supported and the contents of *gadget.yaml* . 4 | 5 | ## Ubuntu Core support 6 | 7 | Ubuntu Core provides a minimalist base that can run on a wide range of hardware, from IoT devices and PC-style platforms to industrial computing. 8 | 9 | - [System requirements](system-requirements) 10 | - [Testing platforms](testing-platforms) 11 | - [Release notes](release-notes) 12 | 13 | ## Image creation 14 | 15 | Configuration and security options. 16 | 17 | - [Gadget snap format](gadget-snap-format) 18 | - [Kernel boot parameters](kernel-boot-parameters) 19 | - [Assertions](assertions/index) 20 | 21 | ```{toctree} 22 | :hidden: 23 | :titlesonly: 24 | :maxdepth: 2 25 | :glob: 26 | 27 | System requirements 28 | Testing platforms 29 | Release notes 30 | Gadget snap format 31 | Kernel boot parameters 32 | Assertions 33 | -------------------------------------------------------------------------------- /docs/reference/kernel-boot-parameters.md: -------------------------------------------------------------------------------- 1 | (reference-kernel-boot-parameters)= 2 | # Kernel boot parameters 3 | 4 | Kernel boot parameters are used to enable, disable or configure kernel-specific features when the system boots. 5 | 6 | On Ubuntu Core, when using the default GNU GRUB bootloader, kernel boot parameters can be configured either in the [Gadget snap](/reference/gadget-snap-format), or through [system options](https://snapcraft.io/docs/system-options). See [Modifying kernel boot parameters](/how-to-guides/manage-ubuntu-core/modify-kernel-options) for further details on each process. It is still possible to use this kernel parameters if not using GRUB, although the way to modify them will depend then on system. 7 | 8 | Alongside parameters supported by the kernel, such as `splash` to display the [Splash screen configuration](/how-to-guides/image-creation/add-a-splash-screen), Ubuntu Core supports the following additional kernel parameters that permit special access to the system. 9 | 10 | ## snapd.debug 11 | 12 | If `snapd.debug` is set to `1`, debug traces for snapd and other commands included in the snapd snap will be produced. They will be accessible from the journal: 13 | 14 | ``` 15 | $ sudo journalctl --no-pager -l -u snapd 16 | Aug 20 16:00:47 host snapd[792]: logger.go:99: DEBUG: will consider standby after: 5s 17 | Aug 20 16:00:47 host snapd[792]: logger.go:99: DEBUG: Setting up sd_notify() watchdog timer every 2m30s 18 | Aug 20 16:00:47 host snapd[792]: logger.go:99: DEBUG: activation done in 321ms 19 | Aug 20 16:00:47 host systemd[1]: Started snapd.service - Snap Daemon. 20 | Aug 20 16:00:47 host snapd[792]: logger.go:99: DEBUG: pid=768;uid=0;socket=/run/snapd.socket; GET /v2/snaps/system/conf?keys=seed.loaded 129.97647ms 200 21 | ... 22 | ``` 23 | 24 | ## ubuntu_core.bootchart 25 | 26 | The [systemd-bootchart](https://manpages.ubuntu.com/manpages/jammy/man1/systemd-bootchart.1.html) performance graphing tool is a standard feature of the Linux Systemd initialisation and service manager. 27 | 28 | _Bootchart_ collects metrics on CPU load, memory usage and process resources during a system boot. On Ubuntu Core, the sample collector will run until the system is seeded, stopping when when the `snapd.seeded.service` stops. It then renders these details as text and charts into an SVG-formatted image file. 29 | 30 | ![Ubuntu Core bootchart graphs](https://assets.ubuntu.com/v1/d39bae51-bootchart-graph.png) 31 | This feature is enabled either as a [Static boot option](/how-to-guides/manage-ubuntu-core/modify-kernel-option.md#static-boot-option-modifications) in the gadget snap, or as a [Dynamic parameter modification](/how-to-guides/manage-ubuntu-core/modify-kernel-option.md#dynamic-kernel-parameter-modifications) with the `snap set` command: 32 | 33 | ``` 34 | snap set system system.kernel.dangerous-cmdline-append="ubuntu_core.bootchart" 35 | sudo reboot 36 | ``` 37 | 38 | Generated bootcharts are stored in the [ubuntu-data](/explanation/full-disk-encryption.md#storage-layouts) partition, under `/var/log/debug/boot/` , where `` is the boot number since _bootcharts_ was enabled. If a chart has also been collected by the initramfs, it's same folder. 39 | 40 | The file names will include the date and time of the boot: 41 | 42 | ```bash 43 | -rw-r--r-- 1 root root 382502 Jul 11 11:30 bootchart-20230711-1130.svg 44 | -rw-r--r-- 1 root root 133684 Jul 11 11:30 initrd-bootchart-20230711-1130.svg 45 | ``` 46 | 47 | To remove a dynamically set kernel command, use the `snap unset` command: 48 | 49 | ```bash 50 | snap unset system system.kernel.dangerous-cmdline-append 51 | ``` 52 | 53 | ## snapd_system_disk 54 | 55 | Requires _snapd 2.59_. 56 | 57 | This kernel boot parameter is used to specify which system storage device is used for booting as a _sysfs_ `/dev` device location: 58 | 59 | ```yaml 60 | snapd_system_disk=/dev/sda 61 | ``` 62 | 63 | -------------------------------------------------------------------------------- /docs/reference/system-requirements.md: -------------------------------------------------------------------------------- 1 | (reference-system-requirements)= 2 | # System requirements 3 | 4 | Ubuntu Core provides a minimalist base that can run on a wide range of hardware, from IoT devices and PC-style platforms to industrial computing. 5 | 6 | Requirements are flexible, but they're generally constrained by the following minimum values. 7 | 8 | ## Architecture 9 | 10 | Ubuntu Core supports various 64-bit architectures and 32-bit Arm. 11 | 12 | - amd64 (Intel/AMD 64-bit) 13 | - arm64 (64-bit Arm) 14 | - armhf (32-bit Arm) 15 | - riscv64 (64-bit RISC-V) 16 | 17 | For specific platforms, see our list of [Ubuntu certified devices](https://ubuntu.com/certified/iot). 18 | 19 | Pre-built testing images are also available for a range of devices. See [Supported testing platforms](/reference/testing-platforms) for further details. 20 | 21 | [Get in touch](https://ubuntu.com/core/contact-us?product=core-overview) to discuss more constrained or specific requirements. 22 | 23 | ## Memory 24 | 25 | **Minimum RAM**: 512MB 26 | 27 | It's likely that devices will include much more on-board RAM, which Ubuntu Core can take full advantage of. 28 | 29 | ## Storage 30 | 31 | **Minimum storage**: 1GB 32 | 33 | Most storage devices are supported, including eMMC and SSD devices. One exception is NAND flash memory, which is not supported. 34 | 35 | We also support custom hardware storage configuration, including hardware rate configuration, as described below. 36 | 37 | ## Full disk encryption 38 | 39 | Full disk encryption support requires both [UEFI Secure Boot](https://wiki.ubuntu.com/UEFI/SecureBoot) and TPM 2.0 (Trusted Platform Module) support. A device will also need an IOMMU to secure data transfers. 40 | 41 | External I2C/SPI-based TPM modules are not currently supported. 42 | 43 | Otherwise, the full disk encryption implementation in Ubuntu Core is generic and widely compatible to help support a range of hardware. 44 | 45 | For a non-standard (non-UEFI+TPM platform) FDE platform, such as a Raspberry Pi or other ARM devices, implementation is board-specific and will typically involve creating custom gadget and kernel snaps. UC20/UC22, however, do provide a helper mechanism, via a hook interface, to ensure the integrity of any subsequently executed or accessed data. 46 | 47 | See [Full disk encryption](/explanation/full-disk-encryption) for further details. 48 | 49 | -------------------------------------------------------------------------------- /docs/reference/testing-platforms.md: -------------------------------------------------------------------------------- 1 | (reference-testing-platforms)= 2 | # Testing platforms 3 | 4 | These images are a great way to quickly get started with Ubuntu Core and to explore Ubuntu Core's features and evaluate its potential. Canonical produces official images for the following platforms: 5 | 6 | | Platform / model name | Model links | Image links | 7 | |--------------------------|-------------------|-----------| 8 | | **Generic x86**
`ubuntu-core-24`
`ubuntu-core-22`
`ubuntu-core-20`
| [core-24-amd64][24-amd64-model]
[core-22-amd64][22-amd64-model]
[core-20-amd64][20-amd64-model]
| [core-24-amd64][24-amd64]
[core-22-amd64][22-amd64]
[core-20-amd64][20-amd64]
| 9 | | **Raspberry Pi 5**
`ubuntu-core-24-pi`
| [core-24-pi-arm64][24-pi-arm64-model]
| [core-24-pi-arm64][24-pi-arm64]
| 10 | | **Raspberry Pi 4**
`ubuntu-core-24-pi`
`ubuntu-core-22-pi`
`ubuntu-core-20-pi`
| [core-24-pi-arm64][24-pi-arm64-model]
[core-22-pi-armhf][22-pi-armhf-model]
[core-22-pi-arm64][22-pi-arm64-model]
[core-20-pi-armhf][20-pi-armhf-model]
[core-20-pi-arm64][20-pi-arm64-model]

| [core-24-pi-arm64][24-pi-arm64]
[core-22-pi-armhf][22-pi-armhf]
[core-22-pi-arm64][22-pi-arm64]
[core-20-pi-armhf][20-pi-armhf]
[core-20-pi-arm64][20-pi-arm64]

| 11 | | **Raspberry Pi 3, CM3 and Zero 2 W**
`ubuntu-core-22-pi`
`ubuntu-core-20-pi`
| [core-22-pi-armhf][22-pi-armhf-model]
[core-22-pi-arm64][22-pi-arm64-model]
[core-20-pi-armhf][20-pi-armhf-model]
[core-20-pi-arm64][20-pi-arm64-model]
| [core-22-pi-armhf][22-pi-armhf]
[core-22-pi-arm64][22-pi-arm64]
[core-20-pi-armhf][20-pi-armhf]
[core-20-pi-arm64][20-pi-arm64]
| 12 | | **Raspberry Pi 2**
`ubuntu-core-22-pi`
`ubuntu-core-20-pi`
| [core-22-pi-armhf][22-pi-armhf-model]
[core-20-pi-armhf][20-pi-armhf-model] | [core-22-pi-armhf][22-pi-armhf]
[core-20-pi-armhf][20-pi-armhf] | 13 | 14 | 15 | **Ubuntu Core 24** (UC24) images are available from:
16 | [http://cdimage.ubuntu.com/ubuntu-core/24/stable/current/](http://cdimage.ubuntu.com/ubuntu-core/24/stable/current/) 17 | 18 | **Ubuntu Core 22** (UC22) images are available from:
19 | [http://cdimage.ubuntu.com/ubuntu-core/22/stable/current/](http://cdimage.ubuntu.com/ubuntu-core/22/stable/current/) 20 | 21 | **Ubuntu Core 20** (UC20) images are available from:
22 | [http://cdimage.ubuntu.com/ubuntu-core/20/stable/current/](http://cdimage.ubuntu.com/ubuntu-core/20/stable/current/) 23 | 24 | 25 | Ubuntu community members also work with, and produce, images for other platforms and CPUs. Refer to these individual projects for more information on what other unofficial images might work for your use cases. 26 | 27 | 28 | 29 | [24-pi-arm64]: https://cdimage.ubuntu.com/ubuntu-core/24/stable/current/ubuntu-core-24-arm64+raspi.img.xz 30 | [24-amd64]: https://cdimage.ubuntu.com/ubuntu-core/24/stable/current/ubuntu-core-24-amd64.img.xz 31 | [22-pi-armhf]: https://cdimage.ubuntu.com/ubuntu-core/22/stable/current/ubuntu-core-22-armhf+raspi.img.xz 32 | [22-amd64]: https://cdimage.ubuntu.com/ubuntu-core/22/stable/current/ubuntu-core-22-amd64.img.xz 33 | [22-pi-arm64]: https://cdimage.ubuntu.com/ubuntu-core/22/stable/current/ubuntu-core-22-arm64+raspi.img.xz 34 | [20-pi-armhf]: https://cdimage.ubuntu.com/ubuntu-core/20/stable/current/ubuntu-core-20-armhf+raspi.img.xz 35 | [20-amd64]: https://cdimage.ubuntu.com/ubuntu-core/20/stable/current/ubuntu-core-20-amd64.img.xz 36 | [20-pi-arm64]: https://cdimage.ubuntu.com/ubuntu-core/20/stable/current/ubuntu-core-20-arm64+raspi.img.xz 37 | 38 | [24-pi-arm64-model]: https://github.com/canonical/models/blob/master/ubuntu-core-24-pi-arm64.json 39 | [24-amd64-model]: https://github.com/canonical/models/blob/master/ubuntu-core-24-amd64.json 40 | [22-pi-armhf-model]: https://github.com/canonical/models/blob/master/ubuntu-core-22-pi-armhf.json 41 | [22-amd64-model]: https://github.com/canonical/models/blob/master/xinyi-classic-22-amd64.json 42 | [22-pi-arm64-model]: https://github.com/canonical/models/blob/master/ubuntu-core-22-pi-arm64.json 43 | [20-pi-armhf-model]: https://github.com/canonical/models/blob/master/ubuntu-core-22-pi-armhf.json 44 | [20-amd64-model]: https://github.com/canonical/models/blob/master/ubuntu-core-20-amd64.json 45 | [20-pi-arm64-model]: https://github.com/canonical/models/blob/master/ubuntu-core-20-pi-arm64.json 46 | 47 | -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | canonical-sphinx[full] 2 | sphinxcontrib-svg2pdfconverter[CairoSVG] 3 | sphinx-last-updated-by-git 4 | sphinxext-rediraffe 5 | -------------------------------------------------------------------------------- /docs/reuse/links.txt: -------------------------------------------------------------------------------- 1 | .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ 2 | .. _MyST style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/ 3 | .. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical 4 | .. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs 5 | .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ 6 | .. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html 7 | .. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html 8 | .. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html 9 | .. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ 10 | .. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ 11 | .. _`Sphinx`: https://www.sphinx-doc.org/ 12 | .. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx 13 | .. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log 14 | .. _Open Graph: https://ogp.me/ 15 | .. _manual import: https://readthedocs.com/dashboard/import/manual/ 16 | .. _How to manually configure a Git repository integration: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html 17 | .. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html 18 | .. _Markdown: https://commonmark.org/ 19 | .. _MyST: https://myst-parser.readthedocs.io/ 20 | .. _Diátaxis: https://diataxis.fr/ 21 | .. _Pa11y: https://pa11y.org/ 22 | .. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration 23 | .. _More useful markup: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#more-useful-markup 24 | .. _Vale: https://vale.sh/ 25 | .. _Vale rules: https://github.com/canonical/praecepta 26 | .. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ 27 | .. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance 28 | 29 | .. SHORTCUTS 30 | .. |RST| replace:: :abbr:`reST (reStructuredText)` 31 | -------------------------------------------------------------------------------- /docs/tutorials/build-your-first-image/access-ubuntu-one.md: -------------------------------------------------------------------------------- 1 | # Access Ubuntu One 2 | 3 | To use Ubuntu Core, to build and sign an image, or publish a snap, you need an [Ubuntu One](https://login.ubuntu.com/) account. 4 | 5 | Ubuntu One is a single sign-on service (SSO) for Ubuntu and its affiliated projects, including [snapcraft.io](https://snapcraft.io), the central resource for all snap-related publishing. 6 | 7 | See below for details on how to create an account, login, and retrieve your developer account details. 8 | 9 | ## Create an Ubuntu One account 10 | 11 | You will need an [Ubuntu One account](https://snapcraft.io/account) with an uploaded public key of a locally generated SSH key pair. 12 | 13 | See [Use Ubuntu One for SSH](/how-to-guides/manage-ubuntu-core/use-ubuntu-one-ssh) for instructions on how to create an account and register an SSH key. With this done, your Ubuntu One account is ready to use. 14 | 15 | You will now need to retrieve your developer account identifier. This is part of your Ubuntu One account and is used to link your account to any Ubuntu Core images you create. 16 | 17 | The next steps need to be performed in an existing Ubuntu LTS environment. 18 | 19 | ## Snapcraft credentials 20 | 21 | Your developer identifier can be retrieved with the [`snapcraft`](https://snapcraft.io/docs/snapcraft-overview) command, the tool that's also used to build and publish snaps. It can be installed by running: 22 | 23 | ```bash 24 | sudo snap install snapcraft --classic 25 | ``` 26 | 27 | We now need to use `snapcraft` to export your login authentication credentials, and to place them within an environment variable: 28 | 29 | ```bash 30 | snapcraft export-login credentials.txt 31 | export SNAPCRAFT_STORE_CREDENTIALS=$(cat credentials.txt) 32 | ``` 33 | 34 | You will be asked for your Ubuntu One email address and password, and encouraged to enable two-factor authentication (2FA) if you haven't already done so. 35 | 36 | ## Retrieve your developer account ID 37 | 38 | With your authentication in place, the `snapcraft whoami` command will now display your developer identifier after the `id` field: 39 | 40 | ```bash 41 | $ snapcraft whoami 42 | email: 43 | username: 44 | id: xSfWKGdLoQBoQx88 45 | permissions: package_access, package_manage, package_metrics, package_push, package_register, package_release, package_update 46 | channels: no restrictions 47 | expires: 2024-04-17T10:25:13.675Z 48 | ``` 49 | 50 | In the output above, the example **id** is `xSfWKGdLoQBoQx88` -- we'll use this ID for subsequent examples, but you should obviously use your own ID from now on. 51 | 52 | -------------------------------------------------------------------------------- /docs/tutorials/build-your-first-image/build-the-image.md: -------------------------------------------------------------------------------- 1 | # Build the image 2 | 3 | Images are built from the recipe contained in the [model assertion](/tutorials/build-your-first-image/create-a-model) using [ubuntu-image](https://github.com/canonical/ubuntu-image), a tool to generate a bootable image. 4 | 5 | ## Compile the image 6 | 7 | First, install the `ubuntu-image` command from its snap: 8 | 9 | ``` 10 | sudo snap install ubuntu-image --classic 11 | ``` 12 | 13 | The `ubuntu-image` command requires two arguments; `snap` to indicate we're building a snap-based Ubuntu Core image, and the filename of our previously-signed model assertion to build an image: 14 | 15 | ```bash 16 | $ ubuntu-image snap my-model.model 17 | [0] prepare_image 18 | WARNING: proceeding to download snaps ignoring validations, this default will change in the future. For now use --validation=enforce for validations to be taken into account, pass instead --validation=ignore to preserve current behavior going forward 19 | WARNING: the kernel for the specified UC20+ model does not carry assertion max formats information, assuming possibly incorrectly the kernel revision can use the same formats as snapd 20 | [1] load_gadget_yaml 21 | [2] set_artifact_names 22 | [3] populate_rootfs_contents 23 | [4] generate_disk_info 24 | [5] calculate_rootfs_size 25 | [6] populate_bootfs_contents 26 | [7] populate_prepare_partitions 27 | [8] make_disk 28 | [9] generate_snap_manifest 29 | Build successful 30 | ``` 31 | You can safely ignore both of the above warnings, and the entire process should only take a few minutes (depending on your connectivity), with the creation of a `pi.img` Ubuntu Core image file being the end result. 32 | 33 | ```{admonition} Console-conf as a separate snap in Ubuntu Core 24+ 34 | :class: tip 35 | 36 | The _console-conf_ user-interface that configures the network and system user when a device first boots has migrated to an optional snap in Ubuntu Core 24 and later. 37 | 38 | This is covered in [Create a model assertion](/tutorials/build-your-first-image/create-a-model), but `ubuntu-image` can add `console-conf` at image build time with an additional `--snap console-conf ` argument. For more details on these changes, see [console-conf for device onboarding](/how-to-guides/image-creation/add-console-conf). 39 | ``` 40 | 41 | ## Write the image 42 | 43 | The next step is to write the `pi.img` file to the microSD card. There are many ways to do this, but our recommended way is to use Raspberry Pi Imager. This can be installed from its snap: 44 | 45 | ```bash 46 | sudo snap install rpi-imager 47 | ``` 48 | 49 | After installation, launch Raspberry Pi Imager from the desktop. Click on the first 'Choose OS' button under 'Operating System' and select 'Use custom'. 50 | 51 | This will open a file requester, and you now need to navigate to, and select, the `pi.img` file we generated in the previous step. 52 | 53 | Next, make sure the microSD card is inserted to a connected microSD card reader and select 'Choose storage' under 'Storage'. Your microSD card will be listed and needs to be selected. 54 | 55 | With the microSD card selected, select the final 'Write' button to commence the image writing process. 56 | 57 | When the process completes, you can safely remove the microSD card. 58 | -------------------------------------------------------------------------------- /docs/tutorials/build-your-first-image/index.md: -------------------------------------------------------------------------------- 1 | # Build your first image 2 | 3 | This tutorial will guide you through the steps required to **create your own Ubuntu Core image**, with **your own selection of snaps**, and **install it on a Raspberry Pi**. 4 | 5 | This same process can be used to build Ubuntu Core images for various hardware and devices. 6 | 7 | ## Step-by-step guide 8 | 9 | 1. [Requirements](requirements) 10 | 1. [Create an Ubuntu One account](access-ubuntu-one) 11 | 1. [Create the account online](access-ubuntu-one.md#create-an-ubuntu-one-account) 12 | 1. [Retrieve your developer account id](access-ubuntu-one.md#retrieve-your-developer-account-id) 13 | 1. [Create the model assertion](create-a-model) 14 | 1. [Download a model assertion](create-a-model.md#download-a-model-file) 15 | 1. [Edit the model assertion](create-a-model.md#edit-the-model-file) 16 | 1. [authority-id and brand-id](create-a-model.md#authority-id-and-brand-id) 17 | 1. [timestamp](create-a-model.md#timestamp) 18 | 1. [snaps](create-a-model.md#snaps) 19 | 1. [A complete model assertion](create-a-model.md#complete-model-example) 20 | 1. [Sign the model assertion](sign-the-model) 21 | 1. [Create a key](sign-the-model.md#create-a-key) 22 | 1. [Register the key](sign-the-model.md#register-the-key) 23 | 1. [Sign the model](sign-the-model.md#id1) 24 | 1. [Build and write the image](build-the-image) 25 | 1. [Compile the image](build-the-image.md#compile-the-image) 26 | 1. [Write the image](build-the-image.md#write-the-image) 27 | 1. [Boot the image](boot-the-image) 28 | 1. [Boot Ubuntu Core](boot-the-image.md#boot-ubuntu-core) 29 | 1. [Configure a network connection](boot-the-image.md#configure-a-network-connection) 30 | 1. [Connect to the device](boot-the-image.md#connect-to-the-device) 31 | 32 | ```{toctree} 33 | :hidden: 34 | :titlesonly: 35 | :maxdepth: 2 36 | :glob: 37 | 38 | Requirements 39 | Access Ubuntu One 40 | Create a model 41 | Sign the model 42 | Build the image 43 | Boot the image 44 | -------------------------------------------------------------------------------- /docs/tutorials/build-your-first-image/requirements.md: -------------------------------------------------------------------------------- 1 | # Requirements 2 | 3 | In addition to having a basic understanding of Linux and running commands from the terminal, this tutorial requires the following: 4 | 5 | For the host system used to build the image: 6 | - [Ubuntu 22.04 LTS](https://releases.ubuntu.com/22.04/) or later installed 7 | - MicroSD card reader 8 | - Internet connectivity 9 | - 10GB of free storage space 10 | 11 | The target device: 12 | - Raspberry Pi 4 Model B, or later 13 | - 4GB+ microSD card 14 | - keyboard and display (for setup only) 15 | - Ethernet or wireless network connectivity 16 | 17 | The above requirements are specific to this tutorial. 18 | 19 | Other host distributions can be used, and other [target devices](/reference/testing-platforms) are supported. 20 | -------------------------------------------------------------------------------- /docs/tutorials/build-your-first-image/sign-the-model.md: -------------------------------------------------------------------------------- 1 | # Sign the model 2 | 3 | After a model has been [created or modified](create-a-model), it must be signed with a GPG key to become a _model assertion_. This ensures the model cannot be altered without the key and also links the created image to both the signed version of the model and your [Ubuntu One account](access-ubuntu-one). 4 | 5 | ## Create a key 6 | 7 | First make sure there are no keys already associated with your account by running the `snapcraft list-keys` command (you will only have a key if you've previously signed an assertion; if you already have a key, you can use that one): 8 | 9 | ```bash 10 | $ snapcraft list-keys 11 | No keys have been registered. See 'snapcraft register-key --help' to register a key. 12 | ``` 13 | 14 | Now use `snapcraft` to create a key called **my-model-key** (the name is arbitrary): 15 | 16 | ```bash 17 | $ snapcraft create-key my-model-key 18 | Passphrase: 19 | Confirm passphrase: 20 | ``` 21 | 22 | As shown above, you will be asked for a passphrase. You need to remember this as you'll be prompted to enter it whenever you use the key, including the very next step. 23 | 24 | ```{admonition} Key management 25 | :class: tip 26 | 27 | Rather than creating a key for every device, the same key is typically used across all models or model families. 28 | 29 | ``` 30 | 31 | ## Register the key 32 | 33 | We now need to upload the key and register it with your Ubuntu One account. This is accomplished with register-key: 34 | 35 | ```bash 36 | $ snapcraft register-key my-model-key 37 | Enter your Ubuntu One e-mail address and password. 38 | If you do not have an Ubuntu One account, you can create one at https://snapcraft.io/account 39 | Email: 40 | Password: 41 | 42 | Registering key ... 43 | Done. The key "my-model-key" () may be used to sign your assertions. 44 | ``` 45 | 46 | Regardless of whether you're logged in with snapcraft, you will be asked for your account and password details. You'll also need to unlock the key with your passphrase, and when the process is complete, the `snapcraft list-keys` command will now list the registered key: 47 | 48 | ```bash 49 | $ snapcraft list-keys 50 | Name SHA3-384 fingerprint 51 | * my-model-key 52 | ``` 53 | 54 | ### Update the timestamp 55 | 56 | As mentioned earlier, the timestamp in the model assertion must be set to a time and date _after_ the creation of our key. This means we need to edit `my-model.json` to update the timestamp with the current time. 57 | 58 | ```json 59 | "timestamp": "2022-04-04T10:40:41+00:00", 60 | ``` 61 | 62 | This is a UTC-formatted time and date value, used to denote the assertion's creation time. It needs to be replaced with the current time and date, which can be generated with the following command: 63 | 64 | ```bash 65 | $ date -Iseconds --utc 66 | 2023-09-29T09:29:09+00:00 67 | ``` 68 | 69 | ## Sign the model 70 | 71 | A model assertion is created by feeding the JSON file into the `snap sign` command with your recently-created key name and capturing the output in the corresponding model file: 72 | 73 | ```bash 74 | snap sign -k my-model-key my-model.json > my-model.model 75 | ``` 76 | You will again be asked for your key's passphrase. 77 | 78 | The resultant `my-model.model` file contains the signed model assertion and can now be used to build the image. 79 | 80 | ```{admonition} Signing failed error? 81 | :class: tip 82 | If you encounter a _gpg: signing failed_ error while signing your assertion from a non-desktop session, such as over SSH, run `export GPG_TTY=$(tty)` first. 83 | ``` 84 | 85 | -------------------------------------------------------------------------------- /docs/tutorials/index.md: -------------------------------------------------------------------------------- 1 | (tutorials-index)= 2 | # Tutorials 3 | 4 | This section of our documentation contains step-by-step tutorials to help outline what Ubuntu Core is capable of while helping you achieve specific aims, such as installing Ubuntu Core or building a custom image for your device. 5 | 6 | After you get Ubuntu Core up and running, take a look at our [First steps using Ubuntu Core](/how-to-guides/using-ubuntu-core) guide. 7 | 8 | ## Build an image 9 | 10 | Ubuntu Core has been designed to facilitate the creation, deployment, and management of secure custom images running on your own hardware. 11 | 12 | 13 | * [Build your first Ubuntu Core image](/tutorials/build-your-first-image/index): 14 | 15 | A step-by-step guide to building and testing your own image with your own selection of applications. 16 | 17 | ## Install Ubuntu Core 18 | 19 | Pre-built test images are also available, for both x86-based PC-style hardware and ARM-based platforms. These testing images are ideal for exploration and experimentation but they're not intended for deployment or for use at scale. 20 | 21 | 22 | * [Install and try a pre-built image](/tutorials/try-pre-built-images/index) 23 | 24 | Test a pre-built image within a VM, or by installing Ubuntu Core on either x86-based or ARM-based hardware. 25 | 26 | ```{toctree} 27 | :hidden: 28 | :titlesonly: 29 | :maxdepth: 2 30 | :glob: 31 | 32 | Build your first image 33 | Try pre-built images 34 | -------------------------------------------------------------------------------- /docs/tutorials/try-pre-built-images/index.md: -------------------------------------------------------------------------------- 1 | # Try pre-built images 2 | 3 | Ubuntu Core runs on a variety of hardware, and pre-built images are available for _amd64_ and _ARM_ platforms (among others). These images can also be installed on a virtual machine. 4 | 5 | Pre-built images are ideal for exploration and experimentation, but they are not intended for deployment or use at scale. They include snaps to provide an onboarding and evaluation experience, alongside an SSH connection, and these are unlikely to be required in your own Ubuntu Core deployment. 6 | 7 | Ubuntu Core has instead been designed to facilitate creating, deploying, and managing secure custom images running on your hardware. 8 | 9 | See [Supported testing platforms](/reference/testing-platforms) for links to image downloads, and to learn how to create your own custom image, read our [Build an image](/tutorials/build-your-first-image/index) guide. 10 | 11 | ## Install on a virtual machine 12 | 13 | You can try Ubuntu Core without any specific hardware from within a virtual machine using Multipass on Windows, Mac and Linux. 14 | 15 | * [Install on a VM](install-on-a-vm): Try Ubuntu Core on on a local machine 16 | 17 | ## Install on a generic device 18 | 19 | Ubuntu Core runs on a large range of hardware, and pre-built images are available for amd64 and Raspberry Pi reference platforms. 20 | 21 | - [Use Raspberry Pi imager](install-on-a-device/use-raspberry-pi-imager): install a pre-built Ubuntu Core image on a Raspberry Pi 22 | - [Use the dd command](install-on-a-device/use-the-dd-command): write an Ubuntu Core reference image to internal storage 23 | 24 | ## Install on a specific device 25 | 26 | - [Install on a Renesas RZ/G2L](install-on-a-device/install-on-renesas): Create an image to run on a Renesas RZ/G2L 27 | 28 | 29 | ```{toctree} 30 | :hidden: 31 | :titlesonly: 32 | :maxdepth: 2 33 | :glob: 34 | 35 | Install on a VM 36 | Install on a device 37 | -------------------------------------------------------------------------------- /docs/tutorials/try-pre-built-images/install-on-a-device/index.md: -------------------------------------------------------------------------------- 1 | # Install on a device 2 | 3 | We create pre-built Ubuntu Core images for several testing platforms. These images are a way to explore Ubuntu Core. Canonical produces official images for the [following platforms](https://ubuntu.com/core/docs/supported-platforms). 4 | 5 | ## Image writing 6 | 7 | We recommend first users try pre-built Ubuntu Core images on a Raspberry Pi or Intel NUC, as these range of devices are easy to use and widely accessible. 8 | 9 | - [Use Raspberry Pi imager](use-raspberry-pi-imager): install a pre-built Ubuntu Core image on a Raspberry Pi 10 | - [Use the dd command](use-the-dd-command): write an Ubuntu Core reference image to internal storage 11 | 12 | ## Install on a specific device 13 | 14 | We also provide instructions for building and installing an Ubuntu Core image on a specific device. 15 | 16 | [Install on a Renesas RZ/G2L](install-on-renesas): Install a pre-built testing image on a [Renesas RZ/G2L](https://www.renesas.com/en/products/microcontrollers-microprocessors/rz-mpus/rzg2l-general-purpose-mpu-dual-core-arm-cortex-a55-cpus-and-single-core-cortex-m33-cpu-3d-graphics-and) 17 | 18 | 19 | ```{toctree} 20 | :hidden: 21 | :titlesonly: 22 | :maxdepth: 2 23 | :glob: 24 | 25 | Use Raspberry Pi imager 26 | Use the dd command 27 | Install on a Renesas RZ/G2L 28 | -------------------------------------------------------------------------------- /docs/tutorials/try-pre-built-images/install-on-a-vm.md: -------------------------------------------------------------------------------- 1 | (tutorials-get-started-try-pre-built-images-install-on-a-vm)= 2 | # Install on a VM 3 | 4 | You can try Ubuntu Core without any specific hardware from within a virtual machine using [Multipass](https://multipass.run/) on Windows, Mac and Linux. Multipass has integrated support for the latest Ubuntu Core images and can launch and run virtual machines from a single command. 5 | 6 | > If you need to test your own Ubuntu Core images, see [Test Ubuntu Core with QEMU](/how-to-guides/manage-ubuntu-core/test-on-qemu). QEMU, is more configurable than Multipass and can boot either a supported image or a custom image, with or without TPM emulation and full disk encryption. 7 | 8 | ## Boot Ubuntu Core with Multipass 9 | 10 | If you don't yet have Multipass installed, see [Install Multipass](https://multipass.run/docs/install-multipass). If it's installed, the following command will output its current state: 11 | 12 | ```bash 13 | multipass info 14 | ``` 15 | 16 | ### List available images 17 | 18 | To list which images Multipass currently has available, type `multipass find`. 19 | 20 | The output will include Ubuntu Core images alongside standard Ubuntu images: 21 | 22 | ```text 23 | Image Aliases Version Description 24 | core20 20230119 Ubuntu Core 20 25 | core22 20230717 Ubuntu Core 22 26 | 20.04 ocal 20240129.1 Ubuntu 20.04 LTS 27 | 22.04 ammy,lts 20240126 Ubuntu 22.04 LTS 28 | daily:24.04 noble,devel 20240129 Ubuntu 24.04 LTS 29 | ``` 30 | 31 | ### Launch an image 32 | 33 | To create a new instance and boot your choice of Ubuntu Core image, type: 34 | 35 | ```bash 36 | multipass launch -n 37 | ``` 38 | 39 | For example, the following command will launch and boot core22 with an instance name of `mycore22`: 40 | 41 | ```bash 42 | multipass launch core22 -n mycore22 43 | ``` 44 | 45 | The image is downloaded and locally cached when it's launched for the first time. 46 | 47 | ### Access a running instance 48 | 49 | You can connect to a running instance of Ubuntu Core by opening a shell environment on that running instance: 50 | 51 | ```bash 52 | multipass shell mycore22 53 | ``` 54 | 55 | You are now operating within the Ubuntu Core environment. See [First steps with Ubuntu Core](/how-to-guides/using-ubuntu-core) for suggestions on what to try. 56 | 57 | --------------------------------------------------------------------------------