├── .gitignore ├── docs ├── .sphinx │ ├── _static │ │ ├── tag.png │ │ ├── favicon.png │ │ └── css │ │ │ └── pdf.css │ ├── fonts │ │ ├── Ubuntu-B.ttf │ │ ├── Ubuntu-R.ttf │ │ ├── Ubuntu-RI.ttf │ │ ├── UbuntuMono-B.ttf │ │ ├── UbuntuMono-R.ttf │ │ └── UbuntuMono-RI.ttf │ ├── images │ │ ├── front-page-light.pdf │ │ ├── Canonical-logo-4x.png │ │ └── normal-page-footer.pdf │ ├── pa11y.json │ ├── requirements.txt │ ├── metrics │ │ ├── build_metrics.sh │ │ └── source_metrics.sh │ ├── .markdownlint.json │ ├── .wordlist.txt │ ├── spellingcheck.yaml │ ├── _templates │ │ └── header.html │ └── get_vale_conf.py ├── explanation │ ├── system-snaps │ │ ├── modem-manager │ │ │ ├── 1 │ │ │ ├── debug.md │ │ │ ├── index.md │ │ │ ├── release-notes.md │ │ │ ├── install-modem-manager.md │ │ │ └── using-modem-manager.md │ │ ├── console-conf │ │ │ ├── ssh.png │ │ │ ├── email.png │ │ │ ├── init.png │ │ │ ├── press-enter.png │ │ │ ├── registered.png │ │ │ ├── connectivity.png │ │ │ ├── index.md │ │ │ ├── usage.md │ │ │ └── model.md │ │ ├── upower │ │ │ ├── report-a-bug.md │ │ │ ├── release-notes.md │ │ │ ├── index.md │ │ │ └── install-upower.md │ │ ├── udisks2 │ │ │ ├── report-a-bug.md │ │ │ ├── index.md │ │ │ ├── release-notes.md │ │ │ └── install-udisks2.md │ │ ├── network-manager │ │ │ ├── how-to-guides │ │ │ │ ├── configure-the-snap │ │ │ │ │ ├── default-renderer.md │ │ │ │ │ ├── index.md │ │ │ │ │ ├── wifi-powersave.md │ │ │ │ │ ├── connectivity-check.md │ │ │ │ │ └── debug.md │ │ │ │ ├── configure-cellular-connections.md │ │ │ │ ├── configure-wifi-access-points.md │ │ │ │ ├── configure-shared-connections.md │ │ │ │ ├── index.md │ │ │ │ ├── message-logging.md │ │ │ │ ├── explore-network-status.md │ │ │ │ ├── edit-connections.md │ │ │ │ ├── configure-wifi-connections.md │ │ │ │ ├── networkmanager-and-netplan.md │ │ │ │ ├── routing-tables.md │ │ │ │ └── configure-vpn-connections.md │ │ │ ├── report-a-bug.md │ │ │ ├── index.md │ │ │ ├── install-networkmanager.md │ │ │ └── release-notes.md │ │ ├── index.md │ │ └── bluetooth │ │ │ ├── commands.md │ │ │ ├── bluetooth-snaps.md │ │ │ └── index.md │ ├── stores │ │ ├── index.md │ │ └── store-overview.md │ ├── core-elements │ │ └── index.md │ ├── docker-companion-snap.md │ ├── index.md │ ├── recovery-modes.md │ ├── preseed-performance.md │ ├── community-engagement.md │ └── full-disk-encryption-op-tee.md ├── requirements.txt ├── .gitignore ├── tutorials │ ├── build-your-first-image │ │ ├── requirements.md │ │ ├── access-ubuntu-one.md │ │ ├── build-the-image.md │ │ └── sign-the-model.md │ ├── index.md │ └── try-pre-built-images │ │ ├── index.md │ │ └── install-on-a-vm.md ├── reference │ ├── index.md │ ├── assertions │ │ ├── snap-resource-pair.md │ │ ├── snap-resource-revision.md │ │ ├── store.md │ │ ├── snap-build.md │ │ ├── account.md │ │ ├── snap-revision.md │ │ ├── validation.md │ │ ├── validation-set.md │ │ ├── account-key.md │ │ └── repair.md │ ├── support-duration.md │ ├── system-requirements.md │ └── kernel-boot-parameters.md ├── .readthedocs.yaml ├── how-to-guides │ ├── deploy-an-image │ │ └── index.md │ ├── container-deployment │ │ ├── index.md │ │ ├── run-a-docker-container.md │ │ └── build-an-image-for-docker-deployment.md │ ├── manage-ubuntu-core │ │ ├── index.md │ │ ├── set-system-options.md │ │ ├── seed-debug.md │ │ ├── troubleshooting.md │ │ └── set-system-time.md │ ├── image-creation │ │ ├── index.md │ │ ├── add-console-conf.md │ │ ├── add-custom-snaps.md │ │ └── optimise-boot-speed.md │ └── index.md ├── _static │ └── css │ │ └── cookie-banner.css ├── reuse │ └── links.txt ├── _templates │ ├── header.html │ └── footer.html └── index.md ├── .github └── workflows │ ├── periodic-style-checks.yml │ ├── automatic-doc-checks.yml │ ├── markdown-style-checks.yml │ └── sphinx-python-dependency-build-checks.yml └── README.rst /.gitignore: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/.sphinx/_static/tag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/_static/tag.png -------------------------------------------------------------------------------- /docs/.sphinx/_static/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/_static/favicon.png -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-B.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/Ubuntu-B.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-R.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/Ubuntu-R.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/Ubuntu-RI.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/Ubuntu-RI.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-B.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/UbuntuMono-B.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-R.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/UbuntuMono-R.ttf -------------------------------------------------------------------------------- /docs/.sphinx/fonts/UbuntuMono-RI.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/fonts/UbuntuMono-RI.ttf -------------------------------------------------------------------------------- /docs/.sphinx/images/front-page-light.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/images/front-page-light.pdf -------------------------------------------------------------------------------- /docs/.sphinx/images/Canonical-logo-4x.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/images/Canonical-logo-4x.png -------------------------------------------------------------------------------- /docs/.sphinx/images/normal-page-footer.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/.sphinx/images/normal-page-footer.pdf -------------------------------------------------------------------------------- /docs/explanation/system-snaps/modem-manager/1: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/modem-manager/1 -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/ssh.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/ssh.png -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/email.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/email.png -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/init.png -------------------------------------------------------------------------------- /docs/requirements.txt: -------------------------------------------------------------------------------- 1 | canonical-sphinx[full] 2 | sphinxcontrib-svg2pdfconverter[CairoSVG] 3 | sphinx-last-updated-by-git 4 | sphinxext-rediraffe 5 | sphinx-sitemap 6 | -------------------------------------------------------------------------------- /docs/.sphinx/pa11y.json: -------------------------------------------------------------------------------- 1 | { 2 | "chromeLaunchConfig": { 3 | "args": [ 4 | "--no-sandbox" 5 | ] 6 | }, 7 | "reporter": "cli", 8 | "standard": "WCAG2AA" 9 | } -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/press-enter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/press-enter.png -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/registered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/registered.png -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/connectivity.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/canonical/ubuntu-core-docs/HEAD/docs/explanation/system-snaps/console-conf/connectivity.png -------------------------------------------------------------------------------- /docs/.sphinx/requirements.txt: -------------------------------------------------------------------------------- 1 | canonical-sphinx[full] @ git+https://github.com/canonical/canonical-sphinx@main 2 | sphinx-autobuild 3 | sphinxcontrib-svg2pdfconverter[CairoSVG] 4 | sphinx-last-updated-by-git -------------------------------------------------------------------------------- /docs/explanation/system-snaps/upower/report-a-bug.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-upower-reference-report-a-bug)= 2 | # Report a Bug 3 | 4 | Bugs can be reported [here](https://github.com/canonical/upower-snap). 5 | 6 | When submitting a bug report, please attach system log coming from the journal: 7 | 8 | ```bash 9 | sudo journalctl --no-pager > system-log 10 | ``` 11 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/udisks2/report-a-bug.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-udisks2-reference-report-a-bug)= 2 | # Report a Bug 3 | 4 | Bugs can be reported [here](https://github.com/canonical/udisks2-snap). 5 | 6 | When submitting a bug report, please attach system log coming from the journal: 7 | 8 | ```bash 9 | sudo journalctl --no-pager > system-log 10 | ``` 11 | -------------------------------------------------------------------------------- /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/.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 | -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /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 | Brand accounts 23 | Dedicated snap store 24 | Store scoping 25 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/index.md: -------------------------------------------------------------------------------- 1 | # console-conf 2 | 3 | The console-conf snap is used for the initial configuration of users and 4 | networking on Ubuntu Core. This snap is not meant to be installed in an already 5 | running system, instead it is expected to be included in the model assertion, 6 | making it part of the snaps that are installed on first boot. 7 | 8 | Furthermore, console-conf is considered a development tool as initial 9 | configuration of production devices is expected to happen in different ways. 10 | 11 | **NOTE:** console-conf used to be part of the base snap in UC22 and older 12 | versions, so this snap is used only in UC24 and more modern versions. 13 | 14 | 15 | ```{toctree} 16 | :hidden: 17 | :titlesonly: 18 | :maxdepth: 2 19 | :glob: 20 | 21 | Including in model assertion 22 | Using console-conf 23 | -------------------------------------------------------------------------------- /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-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/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/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 | - [Upower](upower/index) 13 | - [Udisks2](udisks2/index) 14 | 15 | ## Configuration 16 | 17 | The console-conf snap help with device configuration for development images. 18 | 19 | - [Console-conf](console-conf/index) 20 | 21 | ```{toctree} 22 | :hidden: 23 | :titlesonly: 24 | :maxdepth: 2 25 | :glob: 26 | 27 | Bluetooth manager 28 | Modem Manager 29 | Network Manager 30 | Upower 31 | Udisks2 32 | Console-conf 33 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/upower/release-notes.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-upower-reference-release-notes)= 2 | # Release Notes 3 | 4 | You can check with the following command which version you have currently installed: 5 | 6 | ``` 7 | $ snap info upower 8 | name: upower 9 | summary: An abstraction for power devices 10 | publisher: Valentin David (valentin.david) 11 | store-url: https://snapcraft.io/upower 12 | license: unset 13 | description: | 14 | UPower is an abstraction for enumerating power devices, listening 15 | to device events and querying history and statistics. 16 | snap-id: XRBwbVdB9HsebMqoM9H9SKw5DRAfc4is 17 | channels: 18 | 24/stable: 1.90.2-2 2025-09-10 (15) 462kB - 19 | 24/candidate: 1.90.2-2 2025-09-10 (15) 462kB - 20 | 24/beta: 1.90.2-2 2025-09-10 (15) 462kB - 21 | 24/edge: 1.90.2-2-dev 2025-09-10 (11) 462kB - 22 | ``` 23 | 24 | The detailed changelog for each revision can be consulted in the sources for each track: 25 | 26 | * For track 24, [here](https://git.launchpad.net/ubuntu/+source/upower/tree/NEWS?h=applied/ubuntu/noble-updates) 27 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/console-conf/usage.md: -------------------------------------------------------------------------------- 1 | # Using console-conf 2 | 3 | Ubuntu Core images that include console-conf will start a text-mode application when the 4 | system starts for the first time: 5 | 6 | ![Press enter to configure](press-enter.png) 7 | 8 | After the application starts, we will see a message. 9 | 10 | ![Initial message](init.png) 11 | 12 | Then we will be allowed to configure networking for the device, using any ethernet or wifi devices detected. We also have the possibility of bonding them. 13 | 14 | ![Connectivity](connectivity.png) 15 | 16 | After this, we can add an administrator account to the image. The email needs 17 | to be registered in [Ubuntu](https://login.ubuntu.com). 18 | 19 | ![email](email.png) 20 | 21 | In the final step, console-conf will create a user in the device and pull the ssh keys registered in [Ubuntu](https://login.ubuntu.com/ssh-keys), so we can ssh into the device by using them. 22 | 23 | ![Successful registration](registered.png) 24 | 25 | From that point on, after rebooting we will see the registered user in the display: 26 | 27 | ![ssh message](ssh.png) 28 | -------------------------------------------------------------------------------- /docs/explanation/core-elements/index.md: -------------------------------------------------------------------------------- 1 | # Core elements 2 | 3 | Ubuntu Core is built from the same artefacts as the corresponding Ubuntu LTS release, such as [Ubuntu 24.04 LTS (Noble Numbat)](https://releases.ubuntu.com/24.04/) and [Ubuntu 22.04 LTS (Jammy Jellyfish)](https://releases.ubuntu.com/22.04/) for `core24` and `core22` respectively. 4 | 5 | Understanding how these elements come together is key to getting the most out of the system. 6 | 7 | ## Layout, storage and snaps 8 | 9 | How everything fits together, and how Ubuntu Core is different from a traditional classic Ubuntu system. 10 | 11 | - [Inside Ubuntu Core](inside-ubuntu-core): Volume layouts, boot process, snap layout and the REST API 12 | - [Storage layout](storage-layout): Layouts in more detail, including description for each specific partition 13 | - [Snaps in Ubuntu Core](snaps-in-ubuntu-core): Which snaps are using by default, and why 14 | 15 | ```{toctree} 16 | :hidden: 17 | :titlesonly: 18 | :maxdepth: 2 19 | :glob: 20 | 21 | Inside Ubuntu Core 22 | Storage layout 23 | Snaps in Ubuntu Core 24 | -------------------------------------------------------------------------------- /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/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/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 | Support duration 30 | Release notes 31 | Gadget snap format 32 | Kernel boot parameters 33 | Assertions 34 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/bluetooth/commands.md: -------------------------------------------------------------------------------- 1 | # Bluetooth commands 2 | 3 | The purpose of the *bluez* snap is to provide the BlueZ Bluetooth stack. Apart from this it contains various tools shipped with BlueZ itself. The following table lists the commands that are provided by the *bluez* snap: 4 | 5 | | Command | Short description | 6 | |--------------------|---------------------------------------------------| 7 | | bluez.bluetoothctl | An interactive command-line interface to BlueZ | 8 | | bluez.btattach | Attaches a serial UART to the BT stack | 9 | | bluez.btmgmt | An interactive cli to talk to the kernel BT stack | 10 | | bluez.btmon | A bluetooth monitor | 11 | | bluez.hciattach | DEPRECATED in favor of btattach | 12 | | bluez.hciconfig | DEPRECATED in favor of bluetoothctl and btmgmt | 13 | | bluez.hcidump | DEPRECATED in favor of btmon | 14 | | bluez.hcitool | DEPRECATED in favor of bluetoothctl and btmgmt | 15 | | bluez.sdptool | DEPRECATED in favor of bluetoothctl and btmgmt | 16 | -------------------------------------------------------------------------------- /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/explanation/system-snaps/udisks2/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-udisks2-index)= 2 | # Udisks2 3 | 4 | The udisks snap provides a daemon and tools to access and manipulate disks and storage devices. 5 | 6 | The tools carried by the snap allows the user to: 7 | 8 | - Shows high-level and detailed information about disk drives and block devices. 9 | - Mount and unmounting of block devices. 10 | - Block device lock and unlocking. 11 | - Manipulating loop-devices. 12 | - Power off devices for safe removal. 13 | - SMART functionality. 14 | 15 | ## What Udisks2 Offers 16 | 17 | The upstream udisks2 provides interfaces to enumerate and perform operations on disks and storage devices. Any snap with the `udisks2:dbus` interface plug can access the udisksd daemon via the name [org.freedesktop.UDisks2](https://storaged.org/doc/udisks2-api/latest/ch03.html) on the system message bus. 18 | 19 | ## Upstream documentation 20 | 21 | Documentation for the upstream project can be found at [https://storaged.org/doc/udisks2-api/](https://storaged.org/doc/udisks2-api/). 22 | 23 | ```{toctree} 24 | :hidden: 25 | :titlesonly: 26 | :maxdepth: 2 27 | :glob: 28 | 29 | * 30 | */index 31 | -------------------------------------------------------------------------------- /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/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-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/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 | The bluez snap runs the bluetoothd service. This service provides a D-Bus API that can be accessed by other application snaps by connecting to the `bluez:service` slot for the *bluez* interface provided by the bluez snap. 15 | 16 | For this, the application snap must connect to the *bluez* slot by defining a plug, such as in the following *snapcraft.yaml* snippet: 17 | 18 | ```yaml 19 | plugs: 20 | client: 21 | interface: bluez 22 | 23 | apps: 24 | foo: 25 | command: "bin/foo-command" 26 | plugs: [client] 27 | ``` 28 | 29 | If an application requires direct access to the kernel bluetooth stack, the *bluetooth-control* interface should be used instead. Installation of the *bluez* snap is then not required. 30 | -------------------------------------------------------------------------------- /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 | ## Try Ubuntu Core 18 | 19 | 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 specific 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/explanation/system-snaps/console-conf/model.md: -------------------------------------------------------------------------------- 1 | # Including console-conf in a model assertion 2 | 3 | [Model 4 | assertions](https://documentation.ubuntu.com/core/reference/assertions/model/) 5 | define the snaps that a system will install on first boot. 6 | 7 | Adding console-conf would be a matter of adding a snap to the snaps list in the 8 | json source for the assertion, for instance: 9 | 10 | ```json 11 | { 12 | "name": "console-conf", 13 | "type": "app", 14 | "default-channel": "24/stable", 15 | "id": "ASctKBEHzVt3f1pbZLoekCvcigRjtuqw", 16 | "presence": "optional" 17 | } 18 | ``` 19 | 20 | The track for the default channel should match the base (which in the end is 21 | the Ubuntu Core version) of the model assertion. To know the available tracks, 22 | run `snap info console-conf` from the command line. 23 | 24 | In this case we have set the snap as optional, so we can decide at image build 25 | time if we want to include it and then create a development image, or do not 26 | include it to create a production image. 27 | 28 | We can sign the final assertion with 29 | 30 | ```text 31 | $ snap sign model.json > model.assert 32 | ``` 33 | 34 | After this, we can create an image that would include console-conf with 35 | 36 | ```text 37 | $ ubuntu-image snap --snap=console-conf model.assert 38 | ``` 39 | -------------------------------------------------------------------------------- /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/.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/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/upower/index.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-upower-index)= 2 | # Upower 3 | 4 | UPower is an abstraction for enumerating power devices, listening to device events and querying history and statistics. Any application or service on the system can access the [org.freedesktop.UPower](https://upower.freedesktop.org/docs/ref-dbus.html) service via the system message bus, as long as they connect using the [dbus interface](https://snapcraft.io/docs/dbus-interface) to the upower snap. 5 | 6 | UPower is also useful to control the latency of different operations on your computer, which enables you to save significant amounts of power. 7 | 8 | ## What Upower Offers 9 | 10 | The upstream upower project offers a wide range of features and most are available in the snap package. 11 | 12 | The upower snap contains the upower cli tool, which enables: 13 | 14 | - Inspecting battery information 15 | - Inspecting power parameters for various devices 16 | - Monitoring power events 17 | 18 | In addition, the snap carries the upower daemon, which allows other applications and services to connect to, through dbus. To view all the methods supported by the dbus daemon, please refer to the upstream documentation. 19 | 20 | ## Upstream documentation 21 | 22 | Documentation for the upstream project can be found at [https://upower.freedesktop.org/docs/](https://upower.freedesktop.org/docs/). 23 | 24 | ```{toctree} 25 | :hidden: 26 | :titlesonly: 27 | :maxdepth: 2 28 | :glob: 29 | 30 | * 31 | */index 32 | -------------------------------------------------------------------------------- /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/udisks2/release-notes.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-udisks2-reference-release-notes)= 2 | # Release Notes 3 | 4 | You can check with the following command which version you have currently installed: 5 | 6 | ``` 7 | $ snap info udisks2 8 | name: udisks2 9 | summary: D-Bus service to access and manipulate storage devices 10 | publisher: Canonical✓ 11 | store-url: https://snapcraft.io/udisks2 12 | contact: snaps@canonical.com 13 | license: Other Open Source 14 | description: | 15 | The udisks project provides a daemon, tools and libraries to access 16 | and manipulate disks and storage devices. 17 | 18 | Please find the source code for this snap at: 19 | https://git.launchpad.net/ubuntu/+source/udisks2 20 | snap-id: KTyDAsgNZg4u9UBJ63MHn6q12fmUjOfn 21 | channels: 22 | latest/stable: 2.6.4-2 2017-07-17 (100) 3MB - 23 | latest/candidate: 2.6.4-2 2017-06-09 (100) 3MB - 24 | latest/beta: 2.6.4-2 2017-06-07 (100) 3MB - 25 | latest/edge: 2.6.4-3-dev 2017-06-07 (104) 3MB - 26 | 24/stable: 2.10.1-4 2025-09-10 (124) 6MB - 27 | 24/candidate: 2.10.1-4 2025-09-10 (124) 6MB - 28 | 24/beta: 2.10.1-4 2025-09-10 (124) 6MB - 29 | 24/edge: 2.10.1-4-dev 2025-09-10 (120) 6MB - 30 | ``` 31 | 32 | The detailed changelog for each revision can be consulted in the sources for each track: 33 | 34 | * For track 24, [here](https://git.launchpad.net/ubuntu/+source/udisks2/tree/debian/changelog?h=applied/ubuntu/noble-updates) 35 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/upower/install-upower.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-upower-install-upower)= 2 | # Install Upower 3 | 4 | 5 | The Upower 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 (replace 24 with the ubuntu core version you use): 8 | ```bash 9 | snap install upower --channel=24/stable 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 upower 15 | ``` 16 | 17 | **NOTE:** The *upower:bluez* plug only gets connected when the *bluez* snap is installed too. Otherwise it stays disconnected. 18 | 19 | Once the installation has successfully finished the Upower service is running in the background. You can check its current status with 20 | 21 | ```bash 22 | snap services upower 23 | ``` 24 | 25 | Now you have Upower successfully installed. 26 | 27 | ## Tracks and channels 28 | 29 | The upower snap has currently 1 track, the track name will refer to the version of the base snap used. 30 | 31 | * **24**: Contains upstream 1.90.2 and has a core24 base. This is the default channel. 32 | 33 | 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 upower snap. 34 | 35 | -------------------------------------------------------------------------------- /docs/how-to-guides/deploy-an-image/index.md: -------------------------------------------------------------------------------- 1 | # Deploy an image 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 | ## Install on a specific device 6 | 7 | We also provide instructions for building and installing an Ubuntu Core image on a specific device. 8 | 9 | - [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) 10 | - [Install on a MediaTek Genio](install-on-mediatek): Install a pre-built testing image on a [MediaTek Genio](https://www.mediatek.com/products/iot/genio-iot) 11 | 12 | ## Image writing 13 | 14 | For generic devices, we recommend 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. 15 | 16 | - [Use Raspberry Pi imager](/tutorials/try-pre-built-images/use-raspberry-pi-imager): install a pre-built Ubuntu Core image on a Raspberry Pi 17 | - [Use the dd command](/tutorials/try-pre-built-images/use-the-dd-command): write an Ubuntu Core reference image to internal storage 18 | 19 | 20 | ```{toctree} 21 | :hidden: 22 | :titlesonly: 23 | :maxdepth: 2 24 | :glob: 25 | 26 | Install on a Renesas RZ/G2L 27 | Install on a MediaTek Genio 28 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/udisks2/install-udisks2.md: -------------------------------------------------------------------------------- 1 | (explanation-system-snaps-udisks2-install-udisks2)= 2 | # Install Udisks2 3 | 4 | The Udisks2 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. 5 | 6 | You can install the snap with the following command (replace 24 with the ubuntu core version you use): 7 | ```bash 8 | snap install udisks2 --channel=24/stable 9 | ``` 10 | All necessary plugs and slots will be automatically connected within the installation process. You can verify this with: 11 | 12 | ```bash 13 | snap connections udisks2 14 | ``` 15 | 16 | Once the installation has successfully finished the Udisks2 service is running in the background. You can check its current status with 17 | 18 | ```bash 19 | snap services udisks2 20 | ``` 21 | 22 | Now you have Udisks2 successfully installed. 23 | 24 | ## Tracks and channels 25 | 26 | The Udisks2 snap has currently 2 tracks, and with the exception of the ‘latest’, the track name will refer to the version of the base snap used. 27 | 28 | * **24**: Contains upstream 2.10.1 and has a core24 base. This is the version that will be installed by default. 29 | * **latest** : Contains upstream 2.6.4 and has a core16 base. This is an older stale version that is not recommended for installation. 30 | 31 | 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 Udisks2 snap. 32 | -------------------------------------------------------------------------------- /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/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/.sphinx/_templates/header.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /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/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 | - [Updating gadget boot assets](gadget-boot-assets) 16 | - [Create a recovery system from the API](create-a-recovery-system-from-the-api) 17 | - [Use a recovery mode](use-a-recovery-mode) 18 | - [Troubleshooting](troubleshooting) 19 | 20 | ## Customise the system 21 | 22 | Customise Ubuntu Core images and the running environment. 23 | 24 | - [Add a system user](add-a-system-user) 25 | - [Modify kernel options](modify-kernel-options) 26 | - [Set system time](set-system-time) 27 | - [Set system options](set-system-options) 28 | 29 | 30 | ```{toctree} 31 | :hidden: 32 | :titlesonly: 33 | :maxdepth: 2 34 | :glob: 35 | 36 | Test on QEMU 37 | Use Ubuntu One SSH 38 | Upgrade Ubuntu Core 39 | Set system options 40 | Use a recovery mode 41 | Add a system user 42 | Modify kernel options 43 | Updating boot assets 44 | Create a recovery system from the API 45 | Set system time 46 | Debug install modes 47 | Troubleshooting 48 | -------------------------------------------------------------------------------- /docs/reference/support-duration.md: -------------------------------------------------------------------------------- 1 | # Ubuntu Core support duration 2 | 3 | Ubuntu Core follows our [Long Term Support](https://ubuntu.com/about/release-cycle) (LTS) model. Each release includes 10 years of security maintenance. 4 | 5 | A Legacy add-on can be optionally purchased to cover an additional 5 years of security maintenance, resulting in 15 years of coverage overall. The Legacy add-on is available through an [Ubuntu Pro](https://ubuntu.com/pro) subscription. 6 | 7 | ## Version-specific support 8 | 9 | | | Release date | End of standard support | End of Legacy Support | Architecture support with Legacy* | SnapD version in Legacy Support | 10 | | :---- | :---- | :---- | :---- | :---- | :---- | 11 | | Ubuntu Core 16 | Jun 2016 | Jun 2026 | Jun 2031 | amd64, arm64 | 2.61.x | 12 | | Ubuntu Core 18 | Jan 2019 | Jan 2028 | Jun 2033 | amd64, arm64 | - | 13 | | Ubuntu Core 20 | Feb 2021 | Feb 2030 | Jun 2035 | amd64, arm64 | - | 14 | | Ubuntu Core 22 | Jun 2022 | Jun 2032 | Jun 2037 | amd64, arm64 | - | 15 | | Ubuntu Core 24 | Jun 2024 | Jun 2034 | Jun 2039 | amd64, arm64, armhf | - | 16 | 17 | * For additional information applicable to customers under a Maintenance Agreement, please contact your designated Sales Director. 18 | 19 | ```{note} 20 | Supported Ubuntu Core components include the snap daemon (SnapD), the [kernel snap](https://ubuntu.com/kernel/lifecycle) and the [base](https://documentation.ubuntu.com/snapcraft/stable/reference/bases/#base-snap-reference) for each respective release. See [Inside Ubuntu Core](/explanation/core-elements/inside-ubuntu-core) for details on how Ubuntu Core is composed, and the [Ubuntu Pro service description](https://canonical.com/legal/ubuntu-pro#ubuntu-pro-service-description) for Pro support coverage. 21 | ``` 22 | -------------------------------------------------------------------------------- /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/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/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 various platforms. Generic 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](use-raspberry-pi-imager): install a pre-built Ubuntu Core image on a Raspberry Pi 22 | - [Use the dd command](use-the-dd-command): write an Ubuntu Core reference image to internal storage 23 | 24 | 25 | ```{toctree} 26 | :hidden: 27 | :titlesonly: 28 | :maxdepth: 2 29 | :glob: 30 | 31 | Install on a VM 32 | Use Raspberry Pi Imager 33 | Use the dd command 34 | -------------------------------------------------------------------------------- /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 | -------------------------------------------------------------------------------- /.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 | -------------------------------------------------------------------------------- /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/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/index.md: -------------------------------------------------------------------------------- 1 | # Explanation 2 | 3 | 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. 4 | 5 | ## Operations 6 | 7 | Understanding how certain operations work in Ubuntu Core is key to getting the most out of the system. 8 | 9 | - [How installation works](how-installation-works) 10 | - [Refresh control](refresh-control) 11 | - [Remodelling](remodelling) 12 | - [Preseed performance](preseed-performance) 13 | - [Recovery modes](recovery-modes) 14 | - [Docker companion snap](docker-companion-snap) 15 | 16 | ## Security 17 | 18 | A devices data and runtime environment is secure and isolated from other applications and devices. 19 | 20 | - [Security and sandboxing](security-and-sandboxing) 21 | - [Full disk encryption](full-disk-encryption) 22 | 23 | ## Inside Ubuntu Core 24 | 25 | There are many different components in an Ubuntu Core deployment that keep every system updated and secure. 26 | 27 | - [Core elements](core-elements/index) 28 | - [Stores](stores/index) 29 | - [System snaps](system-snaps/index) 30 | 31 | 32 | ```{toctree} 33 | :hidden: 34 | :titlesonly: 35 | :maxdepth: 2 36 | :glob: 37 | 38 | Community engagement 39 | How installation works 40 | Refresh control 41 | Remodelling 42 | Remodel essential snaps 43 | Preseed performance 44 | Docker companion snap 45 | Full disk encryption 46 | Full disk encryption with OP-TEE 47 | Recovery modes 48 | Security and sandboxing 49 | Core elements 50 | Stores 51 | System snaps 52 | 53 | -------------------------------------------------------------------------------- /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/_static/css/cookie-banner.css: -------------------------------------------------------------------------------- 1 | /* Cookie policy styling WILL BE REMOVED when implementation of new theme with vanilla is implemented */ 2 | .cookie-policy { 3 | overflow: auto; 4 | top: 35%; 5 | z-index: 50; 6 | position: fixed; 7 | } 8 | 9 | dialog.cookie-policy { 10 | background-color: var(--color-code-background); 11 | color: var(--color-code-foreground); 12 | height: auto; 13 | max-height: 60vh; 14 | max-width: 40rem; 15 | padding: 0 1rem 0 1rem; 16 | width: auto; 17 | } 18 | 19 | header.p-modal__header { 20 | margin-bottom: .5rem; 21 | } 22 | 23 | header.p-modal__header::after { 24 | background-color: #d9d9d9; 25 | content: ""; 26 | height: 1px; 27 | left: 0; 28 | margin-left: 1rem; 29 | margin-right: 1rem; 30 | position: absolute; 31 | right: 0; 32 | } 33 | 34 | h2#cookie-policy-title.p-modal__title { 35 | align-self: flex-end; 36 | font-size: 1.5rem; 37 | font-style: normal; 38 | font-weight: 275; 39 | line-height: 2rem; 40 | margin: 0 0 1.05rem 0; 41 | padding: 0.45rem 0 0 0; 42 | } 43 | 44 | .cookie-policy p { 45 | font-size: 1rem; 46 | line-height: 1.5rem; 47 | margin-top: 0; 48 | padding-top: .4rem; 49 | } 50 | 51 | .cookie-policy p a { 52 | text-decoration: none; 53 | color: var(--color-link); 54 | } 55 | .cookie-policy button { 56 | border-style: solid; 57 | border-width: 1.5px; 58 | cursor: pointer; 59 | display: inline-block; 60 | font-size: 1rem; 61 | font-weight: 400; 62 | justify-content: center; 63 | line-height: 1.5rem; 64 | padding: calc(.4rem - 1px) 1rem; 65 | text-align: center; 66 | text-decoration: none; 67 | transition-duration: .1s; 68 | transition-property: background-color,border-color; 69 | transition-timing-function: cubic-bezier(0.55,0.055,0.675,0.19); 70 | } 71 | 72 | .cookie-policy button { 73 | background-color: #fff; 74 | border-color: rgba(0,0,0,0.56); 75 | color: #000; 76 | } 77 | 78 | .cookie-policy .p-button--positive { 79 | background-color: #0e8420; 80 | border-color: #0e8420; 81 | color: #fff; 82 | } 83 | -------------------------------------------------------------------------------- /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/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/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/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/_templates/header.html: -------------------------------------------------------------------------------- 1 | 76 | -------------------------------------------------------------------------------- /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/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 | ## Deploy an image 18 | 19 | Pre-built image install guides for testing specific platforms, including devices from MediaTek and Renesas. 20 | 21 | - [Install on a Renesas RZ/G2L](deploy-an-image/install-on-renesas/): Install a pre-built image on a Renesas RZ/G2L device 22 | - [Install on a MediaTek Genio](deploy-an-image/install-on-mediatek/): Install a pre-built image on a MediaTek Genio device 23 | 24 | ## Manage Ubuntu Core 25 | 26 | Maintain and manage your Ubuntu Core systems, including recovery modes, system users, configuration options and kernel options. 27 | 28 | - [Manage Ubuntu Core](manage-ubuntu-core/index) 29 | 30 | ## Container deployment 31 | 32 | 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. 33 | 34 | - [Deploy containers](container-deployment/index) 35 | 36 | 37 | 38 | ```{toctree} 39 | :hidden: 40 | :titlesonly: 41 | :maxdepth: 2 42 | :glob: 43 | 44 | Using Ubuntu Core 45 | Create an image 46 | Deploy an image 47 | Manage Ubuntu Core 48 | Work with containers 49 | -------------------------------------------------------------------------------- /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/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 | -------------------------------------------------------------------------------- /docs/.sphinx/metrics/source_metrics.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # shellcheck disable=all 3 | 4 | VENV=".sphinx/venv/bin/activate" 5 | 6 | files=0 7 | words=0 8 | readabilityWords=0 9 | readabilitySentences=0 10 | readabilitySyllables=0 11 | readabilityAverage=0 12 | readable=true 13 | 14 | # measure number of files (.rst and .md), excluding those in .sphinx dir 15 | files=$(find . -type d -path './.sphinx' -prune -o -type f \( -name '*.md' -o -name '*.rst' \) -print | wc -l) 16 | 17 | # calculate metrics only if source files are present 18 | if [ "$files" -eq 0 ]; then 19 | echo "There are no source files to calculate metrics" 20 | else 21 | # measure raw total number of words, excluding those in .sphinx dir 22 | words=$(find . -type d -path './.sphinx' -prune -o \( -name '*.md' -o -name '*.rst' \) -exec cat {} + | wc -w) 23 | 24 | # calculate readability for markdown source files 25 | echo "Activating virtual environment to run vale..." 26 | source "${VENV}" 27 | 28 | for file in *.md *.rst; do 29 | if [ -f "$file" ]; then 30 | readabilityWords=$(vale ls-metrics "$file" | grep '"words"' | sed 's/[^0-9]*//g') 31 | readabilitySentences=$(vale ls-metrics "$file" | grep '"sentences"' | sed 's/[^0-9]*//g') 32 | readabilitySyllables=$(vale ls-metrics "$file" | grep '"syllables"' | sed 's/[^0-9]*//g') 33 | fi 34 | done 35 | 36 | echo "Deactivating virtual environment..." 37 | deactivate 38 | 39 | # calculate mean number of words 40 | if [ "$files" -ge 1 ]; then 41 | meanval=$((readabilityWords / files)) 42 | else 43 | meanval=$readabilityWords 44 | fi 45 | 46 | readabilityAverage=$(echo "scale=2; 0.39 * ($readabilityWords / $readabilitySentences) + (11.8 * ($readabilitySyllables / $readabilityWords)) - 15.59" | bc) 47 | 48 | # cast average to int for comparison 49 | readabilityAverageInt=$(echo "$readabilityAverage / 1" | bc) 50 | 51 | # value below 8 is considered readable 52 | if [ "$readabilityAverageInt" -lt 8 ]; then 53 | readable=true 54 | else 55 | readable=false 56 | fi 57 | 58 | # summarise latest metrics 59 | echo "Summarising metrics for source files (.md, .rst)..." 60 | echo -e "\ttotal files: $files" 61 | echo -e "\ttotal words (raw): $words" 62 | echo -e "\ttotal words (prose): $readabilityWords" 63 | echo -e "\taverage word count: $meanval" 64 | echo -e "\treadability: $readabilityAverage" 65 | echo -e "\treadable: $readable" 66 | fi 67 | -------------------------------------------------------------------------------- /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/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/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 services. 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/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](/how-to-guides/image-creation/use-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/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. 14 | 15 | With your account created, ensure you first [login](https://snapcraft.io/login) and accept the _Terms and Conditions_. With this done, your Ubuntu One account is ready to use. 16 | 17 | 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. 18 | 19 | The next steps need to be performed in an existing Ubuntu LTS environment. 20 | 21 | ## Snapcraft credentials 22 | 23 | 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: 24 | 25 | ```bash 26 | sudo snap install snapcraft --classic 27 | ``` 28 | 29 | We now need to use `snapcraft` to export your login authentication credentials, and to place them within an environment variable. 30 | 31 | ```bash 32 | snapcraft export-login credentials.txt 33 | export SNAPCRAFT_STORE_CREDENTIALS=$(cat credentials.txt) 34 | ``` 35 | 36 | If you have yet to login to your Ubuntu One account with the `snapcraft` command, you will first be prompted for your email address, password, and second-factor authentication (if used). 37 | 38 | ## Retrieve your developer account ID 39 | 40 | With your authentication in place, the `snapcraft whoami` command will now display your developer identifier after the `id` field: 41 | 42 | ```bash 43 | $ snapcraft whoami 44 | email: 45 | username: 46 | id: xSfWKGdLoQBoQx88 47 | permissions: package_access, package_manage, package_metrics, package_push, package_register, package_release, package_update 48 | channels: no restrictions 49 | expires: 2024-04-17T10:25:13.675Z 50 | ``` 51 | 52 | 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. 53 | 54 | -------------------------------------------------------------------------------- /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/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/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 `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/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-store) 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-snap](https://snapcraft.io/account/register-snap) 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/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/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/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:** {ref}`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) | {ref}`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/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/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.1.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/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/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 --edge 11 | ``` 12 | 13 | The `ubuntu-image` command requires three arguments; `snap` to indicate we're building a snap-based Ubuntu Core image, `--allow-snapd-kernel-mismatch` to ignore a difference in the versions of snapd we're using, and finally, the filename of our previously-signed model assertion to build an image: 14 | 15 | ```bash 16 | $ ubuntu-image snap --allow-snapd-kernel-mismatch 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 | WARNING: snapd 2.68+ is not compatible with a kernel containing snapd prior to 2.68 21 | [1] load_gadget_yaml 22 | [2] set_artifact_names 23 | [3] populate_rootfs_contents 24 | [4] generate_disk_info 25 | [5] calculate_rootfs_size 26 | [6] populate_bootfs_contents 27 | [7] populate_prepare_partitions 28 | [8] make_disk 29 | [9] generate_snap_manifest 30 | Build successful 31 | ``` 32 | You can safely ignore the 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. 33 | 34 | ```{admonition} Console-conf as a separate snap in Ubuntu Core 24+ 35 | :class: tip 36 | 37 | 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. 38 | 39 | 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). 40 | ``` 41 | 42 | ## Write the image 43 | 44 | 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: 45 | 46 | ```bash 47 | sudo snap install rpi-imager 48 | ``` 49 | 50 | After installation, launch Raspberry Pi Imager from the desktop. Click on the first 'Choose OS' button under 'Operating System' and select 'Use custom'. 51 | 52 | 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. 53 | 54 | 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. 55 | 56 | With the microSD card selected, select the final 'Write' button to commence the image writing process. 57 | 58 | When the process completes, you can safely remove the microSD card. 59 | -------------------------------------------------------------------------------- /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/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/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/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/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/_templates/footer.html: -------------------------------------------------------------------------------- 1 |
2 | {# mod: Per-page navigation #} 3 | {% if meta %} 4 | {% if 'sequential_nav' in meta %} 5 | {% set sequential_nav = meta.sequential_nav %} 6 | {% endif %} 7 | {% endif %} 8 | {# mod: Conditional wrappers to control page navigation buttons #} 9 | {% if sequential_nav != "none" -%} 10 | {% if next and (sequential_nav == "next" or sequential_nav == "both") -%} 11 | 12 |
13 |
14 | {{ _("Next") }} 15 |
16 |
{{ next.title }}
17 |
18 | 19 | 20 | {%- endif %} 21 | {% if prev and (sequential_nav == "prev" or sequential_nav == "both") -%} 22 | 23 | 24 |
25 |
26 | {{ _("Previous") }} 27 |
28 | {% if prev.link == pathto(root_doc) %} 29 |
{{ _("Home") }}
30 | {% else %} 31 |
{{ prev.title }}
32 | {% endif %} 33 |
34 | 35 | {%- endif %} 36 | {%- endif %} 37 |
38 |
39 |
40 | {%- if show_copyright %} 41 |
42 | {%- if hasdoc('copyright') %} 43 | {% trans path=pathto('copyright'), copyright=copyright|e -%} 44 | Copyright © {{ copyright }} 45 | {%- endtrans %} 46 | {%- else %} 47 | {% trans copyright=copyright|e -%} 48 | Copyright © {{ copyright }} 49 | {%- endtrans %} 50 | {%- endif %} 51 |
52 | {%- endif %} 53 | 54 | {# mod: removed "Made with" #} 55 | 56 | {%- if last_updated -%} 57 |
58 | {% trans last_updated=last_updated|e -%} 59 | Last updated on {{ last_updated }} 60 | {%- endtrans -%} 61 |
62 | {%- endif %} 63 | 64 | {%- if show_source and has_source and sourcename %} 65 |
66 | Show source 68 |
69 | {%- endif %} 70 |
71 |
72 | {% if has_contributor_listing and display_contributors and pagename and page_source_suffix %} 73 | {% set contributors = get_contributors_for_file(pagename, page_source_suffix) %} 74 | {% if contributors %} 75 | {% if contributors | length > 1 %} 76 | Thanks to the {{ contributors |length }} contributors! 77 | {% else %} 78 | Thanks to our contributor! 79 | {% endif %} 80 |
81 |
    82 | {% for contributor in contributors %} 83 |
  • 84 | {{ contributor[0] }} 85 |
    • 86 | {% endfor %} 87 |
88 | {% endif %} 89 | {% endif %} 90 |
91 |
Manage your tracker settings
92 |
93 | -------------------------------------------------------------------------------- /docs/explanation/community-engagement.md: -------------------------------------------------------------------------------- 1 | # Community engagement 2 | 3 | Ubuntu Core is an open source project hosted by Canonical. We warmly welcome community contributions, suggestions, fixes and constructive feedback. 4 | 5 | We're committed to: 6 | * actively encouraging community contributions 7 | * providing support and help to both established and potential contributors 8 | * managing our capacity planning to facilitate community engagement 9 | * creating a welcoming environment to foster community spirit (see [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct)) 10 | 11 | ## Where to find the project 12 | 13 | Ubuntu Core does not have a its own code repository. It is instead built entirely from [snap packages](/explanation/core-elements/snaps-in-ubuntu-core/) and managed by the snap daemon, snapd. As a result, the source code for the project is split across several locations, alongside any other snap packages that may be installed: 14 | 15 | - **[snapd](https://github.com/snapcore/snapd)** is the background service that manages and maintains snaps, and provides the `snap` command line tool. 16 | - **[gadget snaps](https://github.com/search?q=org%3Asnapcore+gadget&type=repositories)** define and configures system properties specific to one or more devices. 17 | - **[kernel snaps](https://github.com/snapcore/sample-kernels)** define the Linux kernel to run on each system. 18 | - **[base snaps](https://snapcraft.io/docs/base-snaps)** provide the run-time environment and a minimal set of libraries. 19 | 20 | In addition to the above, our [Documentation](https://ubuntu.com/core/docs) is hosted and built from [https://github.com/canonical/ubuntu-core-docs](https://github.com/canonical/ubuntu-core-docs). See [How to contribute](/contributing.md) for further details. 21 | 22 | ## Contributions 23 | 24 | Project contributions can take many forms. We aim to be responsive and help contributors navigate the project to enable them to get involved, regardless of what avenues may be available to specific projects. This includes: 25 | 26 | * Monitoring platforms including Launchpad, GitHub, Discourse, or others for issues, comments, and pull requests. 27 | * Monitoring communication channels, including IRC, Matrix, Discourse, mailing lists, etc. 28 | * Timely responses to questions, suggestions, and requests for help (aiming for 1-4 working days) 29 | * Timely reviews and merging (when appropriate) of submitted contributions 30 | 31 | These actions and responsibilities have been incorporated into our regular team processes to ensure responsiveness proportionate to the capacity of the team/project in question. In particular, we have a daily rotation schedule for issue tracking, forum responses and merge proposals. 32 | 33 | ## Responsibilities 34 | 35 | Both documentation and engineering teams agree to shoulder responsibilities implied by this commitment to target the goals and handle contributions. 36 | 37 | ### Documentation team 38 | 39 | * Identifying suitable docs-related issues in the project and suggesting them to community 40 | * Reviewing contributions for language, style, and formatting 41 | * Providing guidance to community members regarding docs contributions 42 | 43 | ### Engineering team 44 | 45 | * Reviewing contributions for technical correctness and roadmap alignment 46 | * Interacting with community members regarding technical aspects of the project 47 | 48 | ## Get in touch 49 | 50 | You can find the Ubuntu Core team on the Snapcraft forum: 51 | - [https://forum.snapcraft.io/c/snapd/5](https://forum.snapcraft.io/c/snapd/5) 52 | 53 | For interactive discussions, the team can also be found on Matrix.org: 54 | - https://matrix.to/#/#documentation:ubuntu.com 55 | -------------------------------------------------------------------------------- /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/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/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/full-disk-encryption-op-tee.md: -------------------------------------------------------------------------------- 1 | # Full disk encryption with OP-TEE 2 | 3 | OP-TEE is an open source Trusted Execution Environment (TEE) for Arm systems. It provides a _secure world_ that runs alongside the normal operating system. Trusted Applications (TAs) run inside that secure world, while normal-world software calls into them through standard TEE APIs. For [Full disk encryption](full-disk-encryption) (FDE), OP-TEE protects disk-unlock keys. All cryptographic operations happen inside the secure world and _plaintext_ keys are never written to disk. 4 | 5 | ## How Snapd uses OP-TEE 6 | 7 | Snapd (the snap daemon) integrates with a Canonical-provided [OP-TEE TA](https://github.com/canonical/optee-uc-fde) that knows how to seal and unseal LUKS keys inside the secure world. 8 | 9 | During installation, snapd decides how to seal the LUKS disk keys. It first looks for a kernel [`fde-setup` hook](https://snapcraft.io/docs/uc20-fde-hooks#heading--fde-setup), then for the dedicated OP-TEE TA, and finally falls back to TPM-backed sealing. The selection is automatic and requires no user input. 10 | 11 | When OP-TEE is selected, snapd asks the TA to seal the disk key. The TA performs the encryption inside the secure world and hands back the sealed key. The encrypted key is stored on disk so that it can be used to decrypt the LUKS partition later. Note that only the TA can decrypt the sealed key, so storing the sealed key is safe. 12 | 13 | During boot snapd loads the sealed key from disk, asks the TA to decrypt the key, and then uses the plaintext key to unlock the LUKS partition. Then, snapd locks the TA for the rest of the boot so no further requests are accepted. 14 | 15 | ## Prerequisites 16 | 17 | A system must meet the following criteria before using snapd's OP-TEE integration: 18 | 19 | * The installation target should be either an armhf or arm64 Ubuntu Core system. 20 | * The device firmware must ship OP-TEE with the Canonical FDE TA as an early TA. 21 | * The Linux kernel must expose the OP-TEE device nodes, typically `/dev/tee0` and `/dev/teepriv0`. These are provided by the `tee` and `optee` kernel modules. 22 | 23 | ### Bundling the FDE Trusted Application 24 | 25 | The FDE TA must be built as an [early TA](https://optee.readthedocs.io/en/latest/architecture/trusted_applications.html#early-ta) so that OP-TEE loads it together with the firmware before the normal world boots. The [sample gadget](https://github.com/canonical/optee-uc-fde/tree/master/snaps/test-qemu-optee-gadget) shows the workflow in practice. 26 | 27 | 1. Build the TA from the `github.com/canonical/optee-uc-fde` repository. 28 | 1. Build OP-TEE OS with `CFG_EARLY_TA=y` and list the TA in `EARLY_TA_PATHS` alongside any other early TAs. Review the sample gadget's `optee-os` part for an example. 29 | 1. Package the resulting OP-TEE firmware (`tee-header_v2.bin`, `tee-pager_v2.bin`, `tee-pageable_v2.bin`, and `tee.elf`) together with the rest of the boot firmware. 30 | 31 | This ensures that snapd can interface with the TA during installation and subsequent boots. 32 | 33 | ## Migrating from `fde-setup` Hooks 34 | 35 | Earlier OP-TEE deployments used kernel `fde-setup` hooks to interface with OP-TEE. The easiest migration path is to [remodel](remodelling) the device onto a kernel snap that omits those hooks and allows snapd to talk to the TA directly. 36 | 37 | 1. Create a kernel snap that no longer ships the `fde-setup` hook. 38 | 2. Remodel the system to refresh the kernel and reboot. On the first boot after the remodel, snapd detects that no hook is present, reseals the encryption keys through OP-TEE, and stores the new sealed keys. 39 | 40 | Note that an existing TA that might have been used with a hooks-based implementation should still be compatible with snapd's integration. 41 | -------------------------------------------------------------------------------- /docs/how-to-guides/manage-ubuntu-core/seed-debug.md: -------------------------------------------------------------------------------- 1 | # Debug install mode 2 | 3 | When developing an Ubuntu Core image, it's not always easy to investigate what might cause an installation to fail. 4 | 5 | However, it is possible to modify such an image's [gadget snap](/how-to-guides/image-creation/build-a-gadget-snap) to provide an install mode debug shell without affecting the device's overall configuration. This is useful if you're debugging an actual `install-device` hook, for instance, and you want a real shell to run things in rather than just modifying your hook and re-flashing and waiting. The process is outlined below. 6 | 7 | ## Gadget snap modifications 8 | 9 | Two files in the gadget snap need to be updated or created: 10 | 11 | * `install-device`: this hook is used to crudely block the installation from proceeding 12 | * `cmdline.full`: used to modify the kernel command line to enable the shell. 13 | This file is only used on amd64/Grub devices. If you are on an ARM (or not using Grub, you will need to modify the kernel command line yourself. 14 | 15 | ### install-device hook 16 | 17 | The `install-device` hook should contain something similar to the following: 18 | 19 | ```bash 20 | #!/bin/sh 21 | 22 | sleep infinity 23 | ``` 24 | 25 | The above will block the installation from proceeding, allowing unlimited time to examine the system in its potentially broken installation state. 26 | 27 | ### cmdline.full 28 | 29 | The second part involved editing _systemd's_ kernel command line interface to disable the service that takes over a given TTY and replace it with a debug shell with root access. 30 | 31 | This is only for development and should never be left enabled in production. 32 | 33 | The following needs to be placed in `cmdline.full` within your gadget snap: 34 | 35 | ``` 36 | # this is the first serial console, pick a suitable one for your device 37 | console=ttyS0 38 | 39 | # debug things to get more output from snapd 40 | snapd.debug=1 41 | 42 | # these will output more device status/logging to our console, 43 | # which is kinda annoying in that it goes to the same place we 44 | # have our shell, but I think it's more useful to be able to see 45 | # than have a perfectly pristine console, if you have multiple 46 | # consoles you could of course use a different console for 47 | # systemd output and your debug shell 48 | rd.systemd.journald.forward_to_console=1 49 | systemd.journald.forward_to_console=1 50 | 51 | # to disable console-conf from running on ttyS0 so we can setup 52 | # our debug shell there, this is the most key part here, without 53 | # this console-conf will kill/prevent from starting our debug shell 54 | systemd.mask=serial-getty@ttyS0.service 55 | 56 | # create our debug shell on ttyS0 57 | systemd.debug-shell=ttyS0 58 | 59 | # needed in order to allow the debug-shell to run on UC20 60 | dangerous 61 | 62 | # standard Ubuntu Core kernel command line parameters 63 | panic=-1 64 | ``` 65 | 66 | The above should be placed in _cmdline.full_ rather than _cmdline.extra_ because we want to change the default console settings (at least on _amd64_, in the default pc gadget). 67 | 68 | If you're on ARM, or not using Grub, the above arguments need to be transferred to the kernel command line for your boot-loader. 69 | 70 | See [Modify kernel options](/how-to-guides/manage-ubuntu-core/modify-kernel-options) for details on how to incorporate the above files into a gadget snap. 71 | 72 | ## Booting up your device 73 | 74 | The final step is to rebuilt the gadget snap, rebuild your image with the new gadget snap, and flash it to the device. 75 | 76 | After booting your device, it will stop during installation, either because of the issue you're trying to debug, or because of the infinite wait in the install-device-hook. You now have root shell access to your system and can freely examine its state. 77 | -------------------------------------------------------------------------------- /docs/explanation/system-snaps/bluetooth/index.md: -------------------------------------------------------------------------------- 1 | # Bluetooth 2 | 3 | Bluetooth is a standard for wireless communication on short distances. It 4 | defines multiple profiles for different use cases such as music streaming, 5 | serial connections, message exchange, phone calls, and many others. It was 6 | first published in 1994 and since then has it has updated several times. 7 | Bluetooth 5 and its successors are a big step forward to support the IoT market 8 | and it's needs. 9 | 10 | Bluetooth is developed and published by the [Bluetooth Special Interest 11 | Group](http://www.bluetooth.com/) 12 | 13 | ## BlueZ 14 | 15 | BlueZ is the official Linux Bluetooth stack. It provides, in it's modular way, support for the core Bluetooth layers and protocols. 16 | 17 | Currently BlueZ consists of many separate modules: 18 | 19 | * Bluetooth kernel subsystem core 20 | * L2CAP and SCO audio kernel layers 21 | * RFCOMM, BNEP, CMTP and HIDP kernel implementations 22 | * HCI UART, USB, PCMCIA and virtual device drivers 23 | * General Bluetooth and SDP libraries and daemons 24 | * Configuration and testing utilities 25 | * Protocol decoding and analysis tools 26 | 27 | You can find more information about this on the BlueZ upstream homepage [here](http://www.bluez.org/) 28 | 29 | ## Bluetooth interfaces 30 | 31 | On Ubuntu Core there are two 32 | [interfaces](snapcraft.io/docs/supported-interfaces) that define permissions 33 | for the Bluetooth stack: 34 | 35 | * **bluetooth-control**: allows managing the kernel Bluetooth stack. The slot 36 | side is provided by the system. The bluez snap connects to this from its own 37 | plug. 38 | * **bluez**: allows running and using the bluez service. The bluez snap 39 | installs the slot side of this interface which can then be used by a corresponding 40 | snap application plug to interact with the service via the bluez D-Bus interface. 41 | 42 | ## bluez snap tracks 43 | 44 | The bluez snap has different tracks that should be used for different Ubuntu Core releases: 45 | 46 | * 24: Contains upstream 5.72 and has a core24 base. 47 | * 22: Contains upstream 5.64 and has a core22 base. 48 | * 20: Contains upstream 5.53 and has a core20 base. 49 | * latest: Contains upstream 5.48 and has a core base. Despite the unfortunate 50 | name (there are historical reasons for that) it is the oldest version. 51 | 52 | The naming scheme for the *bluez* snap version includes the BlueZ version being 53 | packaged in the snap and a version separated by a hypen for the snap itself. 54 | For instance, the version could be 5.64-7, for BlueZ 5.64 and snap subversion 55 | 7 - whenever the snap is updated but still provides BlueZ version 5.64 the last 56 | digit will be incremented. The 57 | 58 | ```bash 59 | $ snap info bluez 60 | ``` 61 | 62 | command shows the tracks, version and additional metadata for this snap. 63 | 64 | ## Installation 65 | 66 | The *bluez* snap can be installed for a given track with: 67 | 68 | ``` 69 | $ snap install --channel= bluez 70 | ``` 71 | 72 | It is recommended that the track matches the system's Ubuntu Core version. 73 | 74 | ### Check installation 75 | 76 | You can check the _bluez_ snap is installed by using _snap list_: 77 | 78 | ``` 79 | $ snap list 80 | Name Version Rev Tracking Publisher Notes 81 | bluez 5.48-3 284 latest/stable canonical* - 82 | ``` 83 | 84 | To check that the bluez service is running as expected: 85 | 86 | ``` 87 | $ snap services 88 | Service Startup Current Notes 89 | bluez.bluez enabled active - 90 | ``` 91 | 92 | ```{toctree} 93 | :hidden: 94 | :titlesonly: 95 | :maxdepth: 2 96 | :glob: 97 | 98 | Bluetooth commands 99 | Add Bluetooth to snaps 100 | Device pairing 101 | -------------------------------------------------------------------------------- /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 | ```bash 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/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-options.md#static-boot-option-modifications) in the gadget snap, or as a [Dynamic parameter modification](/how-to-guides/manage-ubuntu-core/modify-kernel-options.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/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/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/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](#network-time-synchronisation) 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 | --------------------------------------------------------------------------------