-
Notifications
You must be signed in to change notification settings - Fork 123
JSON fields
This page describes the JSON formatted fields used in the various meta-files for an OS. Together, they describe the installation requirements for each OS to be installed by PINN. For a summary, please see the summary table below.
[m] = Mandatory field [o] = Optional field
This is the main meta-file that is required for each OS. At startup, PINN will scan the /os folder of PINN's boot drive and attached USB drives for folders containing os.json. It will read this file to find any OSes that are suitable to be installed in the current model of Raspberry Pi, according to the "supported_models" field. Each OS that is suitable is listed in the main installation screen according to its Group. The name and description of each OS is shown. It is also required for remote internet installations, but it is only read at installation time (see os_list.json.
This is the name that the OS will be referred as and will be displayed in the installation menu.
This is an important field as it is used as the default basename of other OS installation files, such as the icon filename, the main tar files, and some configuration files. Therefore it should be fairly short and consistent. It is best not to include spaces, but if any are necessary, they will be converted to underscores when used in a filename. It should be the same as the os_name in os_list.json.
This contains a short description of the OS. Please make it as short as possible, because there is limited space on the installation menu to display it.
The icon must be a 40x40 png file. The icon name is normally found by appending ".png" to the base os name and searching in the same location as the os.json file itself.
Date of release in "YYYY-MM-DD" format. If an OS is available from various sources (Sd card, USB, various internet repositories etc), PINN will use the release date to pick the latest one. If the same release date is available from different sources, local versions will be preferred over any remote versions for speed of installation.
A list of partial model names that are suitable. Each supported model string is compared against the current Raspberry Pi Model number to see if it is included as a sub-string. If it is, it is marked as being suitable. The user can override this using the show_all parameter in PINN to show all OSes regardless of suitability.
a decimal number representing a set of bit flags to indicate which RPI models were suitable. This is no longer used. Use supported_models instead.
a list of hex numbers representing the revisions of RPI models that were suitable. This is no longer used. Use supported_models instead.
Indicates if partition_setup.sh is suitable for installing a backup (true/false/"update").
If this field is absent or set to false, PINN will not be able to backup the OS. This may be due to an unsupported filesystem, or an unsuitable partition_setup.sh script. To ensure the OS can be backed up, set this to true, but you must first be sure that the partition_setup.sh script is suitable. This script is run both on first installation AND after a backup is restored. Some OSes need partition_setup.sh to customise some aspects of the OS for multi-boot, but this only needs to be done once, not after being restored from a backup. The script can guard against this by looking for the "restore" environment variable and adjusting its behaviour. Setting "supports_backup" to true indicates this has been done.
Nevertheless, an older installed OS that didn't support backup previously, may have a newer version of partition_setup.sh that does support it. So for this reason, PINN can also look in the partition_setup.sh script for "#supports_backup in PINN" comment on its second line to see if it can upgrade the current partition_setup.sh script to support backup and thus backup an existing installation. In these cases, "supports_backup": "update" can be set.
Sum of partition_size_nominal of all partitions in MiB. When installing multiple OSes to a drive, the nominal_sizes of each OS are summed to see if they will fit on the available space. The nominal size is normally a bare minimum size for installation, which typically only has about 400MB free space. This may not be sufficient to upgrade the OS or run it efficiently.
Checksum of partition_setup.sh file, or URL of remote checksum file. As partition_setup.sh is a script, it could be modified to do unwanted actions. To guard against this, the hash of the script can be stored in os.json and the script will be prevented from running if it does not match.
Version of this release. This is just for information.
Version of kernel used. Just for information
This provides the location of a webpage which will be displayed for further information on this OS, when the info button is clicked.
Default user name.
Default password.
Offset of disk table (RISCOS only)
As the list of available OSes has increased, it has become increasingly harder to navigate them. The Group field provides a category to group similar OSes together for ease of viewing. The main groups used are (General/Minimal/Education/Media/Utility/Games)
Sum of the partition tar file sizes (in bytes), excluding any metafiles. This allows PINN to provide an estimate of installation time when installing.
Indicates that the rootfs of this OS can be installed to a USB device, but the boot partition must remain on the SD card. This allows OSes (or RPi models) that can't boot from a USB device to still benefit from having the rootfs on a faster USB device. If not true, the OS will be hidden when the target is a USB device.
Indicates that this OS can be booted from a USB device (this implies supports_usb_root is also true). If not true, the OS will be hidden when the target is a USB device.
Some OSes cannot support referencing partitions by PARTUUID, which is needed for installation to a USB. However, they can be installed to USB if the partitions are referenced by device name, e.g. /dev/sda. This is a non-preferred method since the device may not always be referenced as /dev/sda if multiple USB devices are attached. This option means the same as supports_usb_root when using device references.
Some OSes cannot support referencing partitions by PARTUUID, which is needed for installation to a USB. However, they can be installed to USB if the partitions are referenced by device name, e.g. /dev/sda. This is a non-preferred method since the device may not always be referenced as /dev/sda if multiple USB devices are attached. This option means the same as supports_usb_boot when using device references.
Indicates that the rootfs of this OS can be installed to an NVME device, but the boot partition must remain on the SD card. This allows OSes (or RPi models) that can't boot from an NVME device to still benefit from having the rootfs on a faster NVME device. If not true, the OS will be hidden when the target is an NVME device.
Indicates that this OS can be booted from an NVME device (this implies supports_nvme_root is also true). If not true, the OS will be hidden when the target is an NVME device.
This file contains the detailed information about each partition of an OS, so that PINN may allocate enough space, create and format them.
The main entry in this file is "partitions" which is a list of structures, one for each partition. Each partition can contain the following fields.
Name of partition (pay attention to OS limitations of case and length). Please do not include spaces.
The type of filesystem to be created: "raw","fat","ext4","ntfs","partclone","unformatted","swap"
This is the minimum size in MiB that is required to create this partition. This is normally the amount of size needed for all the data file content, plus perhaps 100MB for a boot partition, or 400MB for a root partition. This may not be sufficient space to allow the OS to be upgraded, or run properly, so add more if necessary.
This setting indicates if any free drive space will be shared with this partition.
false = partition will be partition_size_nominal in size. True = Remaining free space will be added equally to all such partitions.
Size of tarball (in MiB) before compression. This is typically also the total size of the data file content in this partition. |
Hex code of partition type for parted. (Only needed to override the default)
Specifies a particular partition number for a partition. Particularly useful for specifying primary partitions (2,3,4) or first OS (e.g. 6,7). Note that all partitions must be contiguous, so if this results in a gap, the partitioning will fail.
Force a position to a specific offset in sectors from the beginning of the disk
true = no tarball exists for this partition
Certain OSes (e.g. some Ubuntu) reference their partitions by name, instead of by device or partuuid. Set this to true to force PINN to use the specific partition labels instead of partuuid. This will prevent PINN being able to install multiple copies of that OS.
Checksum of partition's main file (.tar.xz), or URL of remote checksum file.
Marks the partition as active in the MBR
Any additional options required when formatting the partition
It is not feasible for PINN to scan remote repositories to find os.json files, so each repository contains a single os_list_v3.json file that includes summary information about each OS. This is typically an excerpt from the OS's os.json and partitions.json files and should match the same information. However, on installation, PINN will locate the os.json and partitions.json files and use those in preference.
This contains a short description of the OS. Please make it as short as possible, because there is limited space on the installation menu to display it.
a decimal number representing a set of bit flags to indicate which RPI models were suitable. This is no longer used. Use supported_models instead.
The icon must be a 40x40 png file with the same name as the os_name and name fields. This URL indicates where the icon file can be downloaded from. PINN maintains a cache of icons to speed up the boot time, but first boot may be a bit longer as it need to download each one.
Sum of partition_size_nominal of all partitions in MiB. When installing multiple OSes to a drive, the nominal_sizes of each OS are summed to see if they will fit on the available space. The nominal size is normally a bare minimum size for installation, which typically only has about 400MB free space. This may not be sufficient to upgrade the OS or run it efficiently.
a list of hex numbers representing the revisions of RPI models that were suitable. This is no longer used. Use supported_models instead.
Date of release in "YYYY-MM-DD" format. If an OS is available from various sources (Sd card, USB, various internet repositories etc), PINN will use the release date to pick the latest one. If the same release date is available from different sources, local versions will be preferred over any remote versions for speed of installation.
A list of partial model names that are suitable. Each supported model string is compared against the current Raspberry Pi Model number to see if it is included as a sub-string. If it is, it is marked as being suitable. The user can override this using the show_all parameter in PINN to show all OSes regardless of suitability.
On a remote repository, all the slideshow pictures in /slides_vga of an OS need to be archived into a marketing.tar file, located by this url.
This must contain the location of the os.json file so that it can be downloaded for installation.
This is the name that the OS will be referred as and will be displayed in the installation menu.
This is an important field as it is used as the default basename of other OS installation files, such as the icon filename, the main tar files, and some configuration files. Therefore it should be fairly short and consistent. It is best not to include spaces, but if any are necessary, they will be converted to underscores when used in a filename. It should be the same as the name in os.json.
This must contain the location of the partition_setup.sh script, used to make the partitions suitable for multi-boot.
This must contain the location of partitions.json so that it can be downloaded for installation.
This must contain a list of URLs of the tar files for each partition in order.
This script file will customise an OS for multi-boot installation. Once the partitions have been created and the tar files decompressed onto it, PINN will execute this script so that the OS knows where all of its partitions are located. Typically this means adjusting cmdline.txt on the boot partition, and /etc/fstab on the root partition. Some OSes (e.g. Android) require more extensive modifications.
This script will also be executed after an OS backup has been restored. In this instance, the same level of customization may not need to be performed a second time, and indeed in some cases, repeating it may break the OS. Therefore PINN provides an environment variable called "restore" which the script can make use of to alter its behaviour.
If the script is suitable for use during restoration, then the second line of this file should read as: "#supports_backup in PINN". Also "supports_backup" should be set to true in os.json, or "update" if a newer version will be suitable.
| Key | Type | os | os_list | partitions | Use |
|---|---|---|---|---|---|
| "description" | string | m | m | Describes the OS | |
| "feature_level" | integer | o | o | (deprecated) a decimal number representing a set of bit flags to indicate which RPI models were suitable | |
| "icon" | url | o | m | location of icon.png file (file name must be the same as the os_name and name fields) | |
| "marketing_info" | url | m | Location of marketing.tar file (tar of slides in /slides_vga) | ||
| "nominal_size" | integer | m | m | Sum of partition_size_nominal of all partitions in MiB | |
| "os_info" | url | m | location of os.json file | ||
| "os_name" | string | m | Name of the OS (no spaces) (same as name) | ||
| "name" | string | m | Name of the OS (no spaces) (same as os_name) | ||
| "partition_setup" | url | o | location of partition_setup.sh script | ||
| "partitions_info" | url | m | location of partitions.json | ||
| "sha512sum/sha256sum/sha1sum/md5sum" | string | o | Checksum of partition_setup.sh file, or URL of remote checksum file | ||
| "release_date" | string | m | m | Date of release in "YYYY-MM-DD" format | |
| supported_hex_revisions" | Quoted csv | o | o | (deprecated) a list of hex numbers representing the revisions of RPI models that were suitable | |
| "supported_models" | string list | m | m | A list of partial model names that are suitable | |
| "tarballs" | url list | m | list of URLs of tar file for each partition in order | ||
| "version" | string | o | Version of this release | ||
| "kernel" | string | o | Version of kernel used | ||
| "url" | url | o | location of webpage for further info on this OS | ||
| "username" | string | o | Default user name | ||
| "password" | string | o | Default password | ||
| "riscos_offset" | integer | o | Offset of disk table (RISCOS only) | ||
| "group" | string | o | Category to group OS into on PINN menu (General/Minimal/Education/Media/Utitlity/Games) | ||
| "supports_backup" | boolean/string | m | Indicates if partition_setup.sh is suitbale for installing a backup (true/false/"update") | ||
| "download_size" | integer | o | Sum of the partition tar file sizes (in bytes) , excluding any metafiles. | ||
| "supports_usb_root" | boolean | o | o | Supports hybrid installation to USB root using PARTUUID | |
| "supports_sda_root" | boolean | o | o | Supports hybrid installation to USB root using /dev/sdaX | |
| "supports_usb_boot" | boolean | o | o | Supports booting from USB using PARTUUID | |
| "supports_sda_root" | boolean | o | o | Supports booting from USB using /dev/sdX | |
| "partitions" | Struct list | m | A list of structured information, one for each partition | ||
| { | |||||
| "label" | string | m | Name of partition (pay attention to OS limitations of case and length) | ||
| "filesystem_type" | string | m | "raw","fat","ext4","ntfs","partclone","unformatted","swap" | ||
| "partition_size_nominal" | integer | m | Minium size in MiB of partition to create | ||
| "want_maximised" | boolean | m | false = partition will be partition_size_nominal in size. True = Remaining free space will be added equally | ||
| "uncompressed_tarball_size" | integer | m | Size of tarball (in MiB) before compression | ||
| "partition_type" | string | o | Hex code of partition type for parted. Only needed to override the default) | ||
| "requiresPartitionNumber" | integer | o | Specifies a particular partition number for a partition | ||
| "offset_in_sectors" | integer | o | Force a position to a specific offset in sectors from the beginning of the disk | ||
| "empty_fs" | boolean | o | true = no tarball exists for this partition | ||
| "requires_label" | boolean | o | true = Requires a specific partition label | ||
| "sha512sum/sha256sum/sha1sum/md5sum" | string | o | Checksum of partition's main file (.tar.xz), or URL of remote checksum file | ||
| "active" | boolean | o | Marks the partition as active in the MBR | ||
| "mkfs_options" | string | o | Any additional options required when formatting the partition | ||
| } |