Optional CONFIG Fields

Field	Base
Type	String
Acceptable Values	Valid UNIX dirpath or a Valid UNIX filepath.
Req	No
Default	None
Instructions	Specifies the path of the target filesystem to be used as input and to be built on top of. The value to this tag must either be: A folder A mountable image file with the extension .img in the filename A bzip compressed tar file with the extension .tar.bz2 in the filename The filename must have an extension of . img or .tar.bz2; Base is always used when building a new filesystem. Base can be omitted when updating an existing filesystem. If Base is not provided, -f option is mandatory.
Example(s)	"Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs/" "Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.img" "Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.tar.bz2"

Field	PreInstalls
Type	Object
Acceptable Values	Key content: Valid UNIX filepath to a BASH script. Value type: String Value content: enum[host, target, target_copy]
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Pre-Build stage. For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of: "host" is the indicator to execute existing BASH script on the host. "target" is the indicator to execute existing BASH script on the virtualized target. "target_copy" is the indicator to copy existing BASH script on the host to / tmp / of the target filesystem. execute the script in / tmp / on the virtualized target. remove the script in / tmp /of the target filesystem. Host BASH scripts are useful for setting up mirrors or updating DNS servers. The BASH scripts listed are executed in the order specified. The error code returned by each BASH script is validated, and NVIDIA Build-FS will terminate upon the first error and report a message for debugging.
Example(s)	" PreInstalls ": { ??? "${BUILD_FS_DIR}/mirror-setup/setup-mirror.sh": "host", ??? "setup-dns.sh": "target", "${HOME}/crypt_checker.sh": "target_copy" }

Field	CopyTargets
Type	Array
Acceptable Values	Items type: String Items content: Valid UNIX filepaths to CopyTarget BASH scripts or MANIFESTS. or Items type: dict Items content: { "Manifest": "<path to copytarget yaml/script> (String) (Required)", "NvWorkspace": "<path from which files listed in copytarget are copied> (String) (Optional)", "SourceType": "<Copytarget source type> (String) (Optional)", "Args": { "Add": "<args to be added from copytarget cmdline> (String) (Optional)","Del": "<args to be deleted from copytarget cmdline> (Str) (Optional)" } (Optional) }
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more CopyTarget to be executed on the host during?Build stage. See CopyTarget Documentation for more details. The list of CopyTarget are executed in the order specified. Note: If item type is dict, to avoid overriding certain fields, do not specify the field in the dict.
Example(s)	" CopyTargets ": [ ??? "${WORK_DIR}/copytargets/copytarget-libraries.yaml", ??? "${WORK_DIR}/copytargets/copytarget-tools.yaml", { "Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml", "NvWorkspace": "/usr/local/bin/sdk/", "SourceType": "custom" }, { "Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml", "SourceType": "custom", "Args": { "Add": " --string-option1 val1 --bool-option2 ", "Del": " --string-option3 --bool-option2 " } } ]

Field	PostInstalls
Type	Object
Acceptable Values	Key content: Valid UNIX filepath to a BASH script. Value type: String Value content: enum[host, target, target_copy]
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Post-Build stage. For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of: "host" is the indicator to execute existing BASH script on the host. "target" is the indicator to execute existing BASH script on the virtualized target. "target_copy" is the indicator to copy existing BASH script on the host to /tmp/ of the target filesystem. execute the script in /tmp/ on the virtualized target. remove the script in /tmp/ of the target filesystem. Host BASH scripts are useful for setting up mirrors or updating DNS servers. The BASH scripts listed are executed in the order specified. The error code returned by each BASH script is validated, and NVIDIA Build-FS will terminate upon the first error and report a message for debugging.
Example(s)	"PostInstalls": { ??? "${BUILD_FS_DIR}/mirror-setup/teardown-mirror.sh": "host", ??? "teardown-dns.sh": "target", "${HOME}/crypt_priv_files.sh": "target_copy" }

Field	FilesystemCleanup
Type	Array
Acceptable Values	Items type: String Items content: Valid UNIX filepaths
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more target files to be deleted as part of Post-Build stage.
Example(s)	" FilesystemCleanup ": [ ??? "/tmp/temp.txt", ??? "/var/tmp/tmp.log" ]

Field	ImageSize
Type	String
Acceptable Values	64-bit Unsigned Integer enclosed in double quotes.
Req	No
Default	8589934592
Instructions	The size of the partition to which the current image will be expanded to (defaults to 8GB). This is required for determining values Filesystem Metadata values like journal size, inode_size, inode_byte_ratio. This will help create the required number of inodes and journal in the smaller filesystem image generated, considering the image file expansion.
Example(s)	"ImageSize": "4294967296"

Field	FilesystemType
Type	String
Acceptable Values	String must be using characters from the set [A-Za-z0-9_-]
Req	No
Default	standard
Instructions	Specifies the type of filesystem to be created for the CONFIG. This option is forwarded to copytarget while executing the copytarget manifests, and instructs copytarget whether to copy the file, based on rules written inside the copytarget manifest. See CopyTarget Documentation for more details.
Example(s)	"FilesystemType": "standard"

Field	Mirrors
Type	Array
Acceptable Values	Items type: String Items content: Valid Debian mirrors or Items type: dict Items content: { "Path": "<Valid Unix filepath> (String)", (Required) "Type": "enum["local_debian_mirror", local_debian_folder", "debian"] (String)" (Required) } or { "Path": "<Valid Debian mirror> (String)", (Required) "Type": "enum["debian_mirror"] (String)" (Required) }
Req	No
Default	None
Instructions	Specifies zero, one, or more Debian mirrors hosting Debians specified in DebianPackages. If the value is a 'string', ensure these mirror values adhere to the package manager's syntax of mirrors. If the value is a dict, then depending on the value of 'Type', the file path in 'Path' is treated differently: local_debian_folder: Build-FS shall copy the ".deb" files from 'Path' directory to a temporary mirror path in the target filesystem "/var/mirror-<n>" Build-FS shall create a local Debian mirror with the files in /var/mirror-<n> Build-FS shall edit /etc/apt/sources.list of the target to consider /var/mirror-<n> as a local Debian mirror while installing packages. Build-FS shall remove these Debians while cleaning up before generating the filesystem image. local_debian_mirror: Build-FS shall treat 'Path' as a valid Debian mirror Build-FS shall mount this path to the target filesystem at a mount point /mnt/<n> Build-FS shall edit /etc/apt/sources.list of the target to consider /mnt/<n> as a local Debian mirror while installing packages. Build-FS shall umount these paths while cleaning up before generating the filesystem image. debian: Build-FS shall treat the file pointed by 'Path' as a valid Debian Mirror installer. Build-FS shall install the Mirror installer in the target filesystem. Build-FS relies on the installer Debian to contain valid mirror configuration files in /etc/apt/sources.list.d/. These file contents are appended to /etc/apt/sources.list by Build-FS before installing Debian packages. Build-FS shall purge the Mirror installer Debian before generating the filesystem image. debian_mirror: Contents of 'Path' is appended to /etc/apt/sources.list. Ensure these mirror values adhere to the package manager's syntax of mirrors. Ordering of Debian mirrors are preserved. If the field is not provided, target filesystem will not be configured with any apt mirrors.
Example(s)	"Mirrors": [ "deb http://ports.ubuntu.com/ubuntu-ports/ bionic main universe restricted", { "Type": "debian", "Path" : "/tmp/mirror-installer.deb"}, { "Type": "local_debian_mirror", "Path": "/opt/deb_mirror/"}, { "Type": "local_debian_folder", "Path" : "/opt/deb_folder/"}, { "Type": "debian_mirror", "Path": "deb http://ports.ubuntu.com/ubuntu-ports/ bionic-updates main universe restricted"} ]

Field	Users
Type	Object
Acceptable Values	Key content: Unique user identification alphanumeric string Value type: dict Value content: { ??? "<key >": { "UID" : "<User-Identifier in target /etc/passwd>" (String) (Required), "Password": { "HashedPassword" : "<Hashed-Password>" (String) (Required) }, "Username" : "<Username in target /etc/passwd>", (String) (Required) } or Key content: Valid UNIX username requirements Value type: Array with length=2 Value content: [UID(String), passwd(String)] Where UID must be a valid UNIX user identifier and password must be a valid UNIX password. The latter entry is just for legacy support and not recommended to be used.
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more users to be added to the target filesystem. For each key-value pair in the JSON dictionary, a user account is described by its attributes: user-identifier, username, password entry. This entry will either add and update the user account as described by workflow below. The ordering of users to be added is the order of dictionary entries. Ensure usernames, user identifiers, and user passwords are valid UNIX standards. User-identifier is recommended to be above 1000, and not conflicting with existing user identifiers; otherwise, conflicting user-identifiers will be reported as an error. The password entry (i.e. value for the key "Password") is a dictionary with key "HashedPassword" and value hashed-password created using unix crypt algorithm. The alternate way to provide password using plain text is also supported but not preferred due to security reasons as shown below: "Password": "<Password text>" Workflow: Build-FS fetches the user entry's UID attribute in the CONFIG file and then checks if there exists a user account whose identifier matches value of UID in the filesystem described by option "-f" or "Base" . If the user account exists, Build-FS updates the username of that account to what is specified in the user entry of the CONFIG file. If the user account does not exist, Build-FS proceeds to add the user account with the username provided in the user entry of the CONFIG file. In all the cases, the Build-FS sets the user account password to the value corresponding to the password attribute in the user entry of the CONFIG file. Note that Build-FS updates the username's user-group when updating the username of the user account. For example: when renaming username nvidia, with user-group nvidia and UID 1000 to username nvidia2, Build-FS updates the user's group nvidia to nvidia2 keeping same UID 1000. Note that the previous version of Users block where one entry is : "<username>" : ["user-id", "password"], continues to be supported to only add users for backward compatibility but not to update users.
Example(s)	"Users": { "one": { "UID": "1001", "Username" : "nvidia2", "Password": "driveos" }, "two": { "UID": "1002", "Username" : "nvidia3", "Password": { "HashedPassword": "$6$4bhqDdYb$kxJApfqarvpuMhLweydYp7 .NqSFXWxML8N3JywqadmlEp9GF89553PNBAYBTdGmfBaUe7/7LxpP8PBBQlCJT70" }, }

Field	Groups
Type	Object
Acceptable Values	Key content: Unique user identification alphanumeric string Value type: dict Value content: { ??? "<key >": { "GID" : "<Group-Identifier in target /etc/group>" (String) (Required), "Groupname" : "<Group name in target /etc/group>", (String) (Required) } or Key content: Valid UNIX groupname Value type: String Value content: Valid UNIX group identifier The latter entry is just for legacy support and not recommended to be used.
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more groups to be added to the target filesystem. For each key-value pair in the JSON, a group is described by its attributes: groupname and the group-identifier. This entry will either add or update the group as described by workflow below. Ordering of groups to be added is preserved. Ensure group names and group identifiers are valid UNIX standards. Group identifier is recommended to be above 1000, and not conflicting with existing group identifiers; otherwise, conflicting user identifiers will be reported as an error. Workflow: Build-FS fetches the group entry's GID attribute in the CONFIG file and then checks if there exists a group whose identifier matches value of GID in the filesystem described by -f option or "Base" . If the group exists, Build-FS updates the groupname of that account to what is specified in the group entry of the CONFIG file. If the group does not exist, Build-FS proceeds to add the group with the groupname provided in the group entry of the CONFIG file. Note that the previous version of Groups block where one entry is: "<groupname>": "<group-id>", continues to be supported to only add groups for backward compatibility but not to update groups.
Example(s)	"Groups": { "one": { "Groupname": "automotive", "GID": "2001" } }

Field	Memberships
Type	Object
Acceptable Values	Key content: valid UNIX username Value type: Array Value content: [ group1(String),...., groupN(String) ] Where group* must be a valid UNIX groupname or group identifier.
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more group memberships to be added to the target filesystem.
Example(s)	"Memberships": { ??? "nvidia": ???? [ ??????? "1000", ??????? "audio", ??????? "cdrom", ??????? "dialout", ??? ] }

Field	DebianPackages
Type	Array
Acceptable Values	Items type: String Items content: Valid Debian package names.
Req	No
Default	None
Instructions	Specifies a list of zero, one, or more Debian packages to be installed on target filesystem during Build stage. Each Debian package can be accompanied by a valid corresponding package version but is entirely optional. If no package version is specified, the latest version as reported by the Debian mirror will be acquired and installed If the list of Debians and or the specified versions conflict, an error will be reported.
Example(s)	" DebianPackages ": [ ??? "openssh-server=1-4ubuntu0.3", ??? "vim" ]

Field	Hostname
Type	String
Acceptable Values	Valid UNIX hostname
Req	No
Default	None
Instructions	Host name of the target filesystem is updated to the one specified as the value for HostName. If HostName Field is not present in the CONFIG, the host name of the Base filesystem is preserved.
Example(s)	"HostName": "auto-ubuntu"

Field	Mount
Acceptable Values	`Value type: array{` `"<Path of mount point> (Required) (String)": {` `"Type": "<Type of the Linux Filesystem to be mounted> (Required) (String)",` `"MountOptions": "<Mount specific options> (Required) (String)",` `"Device": "<Path to the device node or the partition to mount> (Required) (String)"` `},}` `The values to the Mounts Field is an array of dictionaries. Each dictionary entry's key is the path to the Mount point which the directory the mount the storage device or the partition.` `The dictionary entry's value following the key is the dictionary of 3 key-value pairs where keys are {"Type", "MountOptions", "Device"}.` `The Type is the filesystem type such as ext4, ext3, ext2, nfs, overlayfs, ubifs and so on.` `MountOptions are the comma-separated specific mount options as required. If no specific options are required, it must be assigned as "defaults".` `Device is the path to the device node of the partition that contains the filesystem in Type and must be mounted on the mount-point (referred above) with the options from MountOptions.`
Req	No
Default	None
Instructions	The Mounts entry recorded in Build-FS config is used to generate an /etc/fstab entry and append it to be filesystem's /etc/fstab in the same order as listed in the Mounts block. The block must be populated only when the user is sure of the partition/device in Device contains the filesystem of Type. Entering a Mounts entry without an existing filesystem in the Device leads to a mount error during the filesystem runtime.
Example(s)	`"Mounts": {` `"/home/": {` `"Type": "ext4",` `"MountOptions": "defaults",` `"Device": "/dev/vblkdev3"` `},}` `This example mounts the ext4 filesystem in /dev/vblkdev3 at /home/ with default options.`

Field	FilesystemInclude
Acceptable Values	`Value type: array{` `...,` `"<Path to file to be included> (Required) (String)",` `...,` `"<Path to directory to be included>/ (Required) (String)",` `...}` `The FilesystemInclude block contains the subset of files and directory to be chosen from the Build-FS filesystem working directory after building the filesystem content. The block is optional and if it is absent, the entire Build-FS filesystem working directory goes into the filesystem image. The path to files and the path to directories slightly differ because the path to directory always must end with a slashs to indicate a directory where as the path of a file must not end with a slash.` `The list of paths required must be expressed in absolute path directory in the Build-FS config or defined using intermediate environment variables and in such cases the environment must define variable.`
Default	None
Instructions	The FilesystemInclude block applies when user wishes to copy only a subset of data from filesystem work directory to the final image. However, if the user wants the entire content in the workspace, FilesystemInclude block must to be used.
Example(s)	`"FilesystemInclude": [` `"/etc/group",` `"/etc/gshadow",` `"/etc/passwd",` `"/etc/shadow",` `"/etc/subgid",` `"/etc/subuid",` `"/etc/passwd",` `"/home/"` `],` `This example ensures the files listed (until and excluding /home) are chosen along with /home/ directory and its contents are the subset of data that shall be part of the Build-FS created filesystem image.`

Field	AssociatedFilesystems
Acceptable Values	`Value type: array{` `...` `"<Path to build-fs CONFIG associated with the parent CONFIG OR base filename of build-fs CONFIG> (Required) (String)",` `"<Path to build-fs CONFIG associated with the parent CONFIG OR base filename of build-fs CONFIG> (Required) (String)",` `...}`
Req	No
Default	None
Instructions	The Build-FS CONFIG in AssosciatedFilesystems block can either be an entry to the absolute path of the CONFIG file or just a filename. If it is a filename, then Build-FS looks for the CONFIG in Associated Filesystems in the parent CONFIG's directory. The Build-FS CONFIG in AssosciatedFilesystems block is a valid Build-FS config (no different than the associator's CONFIG). In fact, each CONFIG in the AssociatedFilesystems can be executed as dedicated instances of Build-FS. The AssociatedFilesystems block can be applied recursively such that the Build-FS CONFIG within the AssociatedFilesystems can request more AssociatedFilesystems. Finally, the fields within CONFIG of AssociatedFilesystems are not flattened into the parent Build-FS CONFIG's MANIFEST but instead each CONFIG in ASsociatedFilesystems creates its corresponding MANIFEST.
Example(s)	`"AssociatedFilesystems": [` `"driveos-core-rfs-user-metadata.CONFIG.json",` `"${BUILD_FS_DIR}/configs/driveos-core-rfs-user-data.CONFIG.json"` `],` `This example the first associated filesystem shall be located at the same directory as the parent's CONFIG whereas the final CONFIG must be present at the full path "${BUILD_FS_DIR}/configs/driveos-core-rfs-user-data.CONFIG.json".`

Field	SELinux
Acceptable Values	`Value type: dictValue content:{` `"SetFiles": <Path to the 3rdparty SELinux setfiles application> (String) (Required),` `"PolicyFile": <Path to the SELinux policy binary file> (String) (Required),` `"ContextFile": <Path to SELinux context file> (String) (Required)}` `The value is of type dictionary but the set of keys in the directionary is fixed to {"SetFiles", "PolicyFile", "ContextFile"}.` `The SetFiles key holds the absolute path to host-side setfiles application. This application is provided Ubuntu host-side package check policycoreutils.` `The PolicyFile key holds the absolute path to the SELinux precompiled policy binary file (built using checkpolicy application).` `The ContextFile key holds the absolute path to SELinux context file.` `For more information on SELinux policy and SELinux context file, please refer to DRIVE OS LINUX SELinux documentation.`
Req	No
Default	None
Instructions	The SELinux block specifies the required inputs for build-fs to apply appropriate the SELinux attributes (SELinux attributes is a part of extended attributes of a file or a directory). SELinux block is a dictionary but Build-FS only supports and requires 3-fixed keys {"SetFiles", "PolicyFile", "ContextFile"}. The value of each of the keys must the respective absolute paths. Build-FS supports specifying the paths using environment variables only if such variables are defined the Build-FS environment file. For DRIVE OS LINUX, the setfiles application can be obtained by installing policycoreutils package via apt-get. Then, the app resides at path /sbin/setfiles. The workflow of editing policy and context file is documented in DRIVE OS LINUX SELINUX documentation.
Example(s)	`1) Explcit path to each of the entries."SELinux": {` `"SetFiles": "/sbin/setfiles",` `"PolicyFile": "${NV_WORKSPACE}/drive-linux/filesystem/contents/configs/selinux/policy.30",` `"ContextFile": ${NV_WORKSPACE}/drive-linux/filesystem/contents/configs/selinux/file_contexts"}` `2) Paths can be defined using build-FS environment variable"SELinux": {` `"SetFiles": "${SELINUX_SETFILES_PATH}",` `"PolicyFile": "${SELINUX_POLICY_PATH}",` `"ContextFile": "${SELINUX_CONTEXT_PATH}"}The build-FS environment would contain the expansion of the variables:{...` `"SDKPLATDIR": "${NV_WORKSPACE}/drive-linux",` `"SELINUX_SETFILES_PATH": "/sbin/setfiles",` `"SELINUX_POLICY_PATH": "${SDKPLATDIR}/filesystem/contents/configs/selinux/policy.30",` `"SELINUX_CONTEXT_PATH": "${SDKPLATDIR}/filesystem/contents/configs/selinux/file_contexts",` `...}`

Type

String

Acceptable Values

Valid UNIX dirpath or a Valid UNIX filepath.

Req

No

Default

None

Instructions

Specifies the path of the target filesystem to be used as input and to be built on top of.

The value to this tag must either be:

A folder
A mountable image file with the extension .img in the filename
A bzip compressed tar file with the extension .tar.bz2 in the filename

The filename must have an extension of . img or .tar.bz2;

Base is always used when building a new filesystem.

Base can be omitted when updating an existing filesystem. If Base is not provided, -f option is mandatory.

Example(s)

"Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs/"

"Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.img"

"Base": "/home/nvidia/driveos/nvidia-driveos-base-rfs.tar.bz2"

Field

PreInstalls

Type

Object

Acceptable Values

Key content: Valid UNIX filepath to a BASH script.

Value type: String Value content: enum[host, target, target_copy]

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Pre-Build stage.

For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of:

"host" is the indicator to execute existing BASH script on the host.

"target" is the indicator to execute existing BASH script on the virtualized target.

"target_copy" is the indicator to copy existing BASH script on the host to / tmp / of the target filesystem.

execute the script in / tmp / on the virtualized target.

remove the script in / tmp /of the target filesystem.

Host BASH scripts are useful for setting up mirrors or updating DNS servers.

The BASH scripts listed are executed in the order specified.

The error code returned by each BASH script is validated, and NVIDIA Build-FS will terminate upon the first error and report a message for debugging.

Example(s)

" PreInstalls ":

{

??? "${BUILD_FS_DIR}/mirror-setup/setup-mirror.sh": "host",

??? "setup-dns.sh": "target",

"${HOME}/crypt_checker.sh": "target_copy"

}

Field

CopyTargets

Type

Array

Acceptable Values

Items type: String

Items content: Valid UNIX filepaths to CopyTarget BASH scripts or MANIFESTS.

or

Items type: dict

Items content:

{

"Manifest": "<path to copytarget yaml/script> (String) (Required)",

"NvWorkspace": "<path from which files listed in copytarget are copied> (String) (Optional)",

"SourceType": "<Copytarget source type> (String) (Optional)", "Args": {

"Add": "<args to be added from copytarget cmdline> (String) (Optional)","Del": "<args to be deleted from copytarget cmdline> (Str) (Optional)"

} (Optional)

}

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more CopyTarget to be executed on the host during?Build stage.

See CopyTarget Documentation for more details.

The list of CopyTarget are executed in the order specified.

Note:

If item type is dict, to avoid overriding certain fields, do not specify the field in the dict.

Example(s)

" CopyTargets ":

[

??? "${WORK_DIR}/copytargets/copytarget-libraries.yaml",

??? "${WORK_DIR}/copytargets/copytarget-tools.yaml",

{

"Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml",

"NvWorkspace": "/usr/local/bin/sdk/",

"SourceType": "custom"

},

{

"Manifest": "${WORK_DIR}"/copytargets/copytarget-sdk.yaml",

"SourceType": "custom",

"Args": {

"Add": " --string-option1 val1 --bool-option2 ",

"Del": " --string-option3 --bool-option2 "

}

]

Field

PostInstalls

Type

Object

Acceptable Values

Key content: Valid UNIX filepath to a BASH script.

Value type: String

Value content: enum[host, target, target_copy]

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more BASH scripts to be executed on the host or virtualized target during the Post-Build stage.

For each object element, the value of the element specifies whether the specific script is to be executed on the host or virtualized target. A value of:

"host" is the indicator to execute existing BASH script on the host.

"target" is the indicator to execute existing BASH script on the virtualized target.

"target_copy" is the indicator to

copy existing BASH script on the host to /tmp/ of the target filesystem.

execute the script in /tmp/ on the virtualized target.

remove the script in /tmp/ of the target filesystem.

Host BASH scripts are useful for setting up mirrors or updating DNS servers.

The BASH scripts listed are executed in the order specified.

The error code returned by each BASH script is validated, and NVIDIA Build-FS will terminate upon the first error and report a message for debugging.

Example(s)

"PostInstalls":

{

??? "${BUILD_FS_DIR}/mirror-setup/teardown-mirror.sh": "host",

??? "teardown-dns.sh": "target",

"${HOME}/crypt_priv_files.sh": "target_copy"

}

Field

FilesystemCleanup

Type

Array

Acceptable Values

Items type: String

Items content: Valid UNIX filepaths

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more target files to be deleted as part of Post-Build stage.

Example(s)

" FilesystemCleanup ":

[

??? "/tmp/temp.txt",

??? "/var/tmp/tmp.log"

]

Field

ImageSize

Type

String

Acceptable Values

64-bit Unsigned Integer enclosed in double quotes.

Req

No

Default

8589934592

Instructions

The size of the partition to which the current image will be expanded to (defaults to 8GB).

This is required for determining values Filesystem Metadata values like journal size, inode_size,

inode_byte_ratio.

This will help create the required number of inodes and journal in the smaller filesystem image generated,

considering the image file expansion.

Example(s)

"ImageSize": "4294967296"

Field

FilesystemType

Type

String

Acceptable Values

String must be using characters from the set [A-Za-z0-9_-]

Req

No

Default

standard

Instructions

Specifies the type of filesystem to be created for the CONFIG. This option is forwarded to copytarget while executing the copytarget manifests, and instructs copytarget whether to copy the file, based on rules written inside the copytarget manifest.

See CopyTarget Documentation for more details.

Example(s)

"FilesystemType": "standard"

Field

Mirrors

Type

Array

Acceptable Values

Items type: String

Items content: Valid Debian mirrors

or

Items type: dict

Items content:

{

"Path": "<Valid Unix filepath> (String)", (Required)

"Type": "enum["local_debian_mirror", local_debian_folder", "debian"] (String)" (Required)

}

or

{

"Path": "<Valid Debian mirror> (String)", (Required)

"Type": "enum["debian_mirror"] (String)" (Required)

}

Req

No

Default

None

Instructions

Specifies zero, one, or more Debian mirrors hosting Debians specified in DebianPackages.

If the value is a 'string', ensure these mirror values adhere to the package manager's syntax of mirrors.

If the value is a dict, then depending on the value of 'Type', the file path in 'Path' is treated differently:

local_debian_folder:

Build-FS shall copy the ".deb" files from 'Path' directory to a temporary mirror path in the target filesystem "/var/mirror-<n>"

Build-FS shall create a local Debian mirror with the files in /var/mirror-<n>

Build-FS shall edit /etc/apt/sources.list of the target to consider /var/mirror-<n> as a local Debian mirror while installing packages.

Build-FS shall remove these Debians while cleaning up before generating the filesystem image.

local_debian_mirror:

Build-FS shall treat 'Path' as a valid Debian mirror

Build-FS shall mount this path to the target filesystem at a mount point /mnt/<n>

Build-FS shall edit /etc/apt/sources.list of the target to consider /mnt/<n> as a local Debian mirror while installing packages.

Build-FS shall umount these paths while cleaning up before generating the filesystem image.

debian:

Build-FS shall treat the file pointed by 'Path' as a valid Debian Mirror installer.

Build-FS shall install the Mirror installer in the target filesystem.

Build-FS relies on the installer Debian to contain valid mirror configuration files in /etc/apt/sources.list.d/. These file contents are appended to /etc/apt/sources.list by Build-FS before installing Debian packages.

Build-FS shall purge the Mirror installer Debian before generating the filesystem image.

debian_mirror:

Contents of 'Path' is appended to /etc/apt/sources.list.

Ensure these mirror values adhere to the package manager's syntax of mirrors.

Ordering of Debian mirrors are preserved.

If the field is not provided, target filesystem will not be configured with any apt mirrors.

Example(s)

"Mirrors":

[

"deb http://ports.ubuntu.com/ubuntu-ports/ bionic main universe restricted",

{ "Type": "debian",

"Path" : "/tmp/mirror-installer.deb"},

{ "Type": "local_debian_mirror",

"Path": "/opt/deb_mirror/"},

{ "Type": "local_debian_folder",

"Path" : "/opt/deb_folder/"},

{ "Type": "debian_mirror",

"Path": "deb http://ports.ubuntu.com/ubuntu-ports/ bionic-updates main universe restricted"}

]

Field

Users

Type

Object

Acceptable Values

Key content: Unique user identification alphanumeric string

Value type: dict

Value content:

{

??? "<key >": {

"UID" : "<User-Identifier in target /etc/passwd>" (String) (Required),

"Password": {

"HashedPassword" : "<Hashed-Password>" (String) (Required)

},

"Username" : "<Username in target /etc/passwd>", (String) (Required)

}

or

Key content: Valid UNIX username requirements

Value type: Array with length=2

Value content: [UID(String), passwd(String)]

Where UID must be a valid UNIX user identifier and password must be a valid UNIX password.

The latter entry is just for legacy support and not recommended to be used.

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more users to be added to the target filesystem.

For each key-value pair in the JSON dictionary, a user account is described by its attributes: user-identifier, username, password entry. This entry will either add and update the user account as described by workflow below. The ordering of users to be added is the order of dictionary entries.

Ensure usernames, user identifiers, and user passwords are valid UNIX standards.

User-identifier is recommended to be above 1000, and not conflicting with existing user identifiers; otherwise, conflicting user-identifiers will be reported as an error.

The password entry (i.e. value for the key "Password") is a dictionary with key "HashedPassword" and value hashed-password created using unix crypt algorithm. The alternate way to provide password using plain text is also supported but not preferred due to security reasons as shown below:

"Password": "<Password text>"

Workflow:

Build-FS fetches the user entry's UID attribute in the CONFIG file and then checks if there exists a user account whose identifier matches value of UID in the filesystem described by option "-f" or "Base" .

If the user account exists, Build-FS updates the username of that account to what is specified in the user entry of the CONFIG file.

If the user account does not exist, Build-FS proceeds to add the user account with the username provided in the user entry of the CONFIG file.

In all the cases, the Build-FS sets the user account password to the value corresponding to the password attribute in the user entry of the CONFIG file.

Note that Build-FS updates the username's user-group when updating the username of the user account. For example: when renaming username nvidia, with user-group nvidia and UID 1000 to username nvidia2, Build-FS updates the user's group nvidia to nvidia2 keeping same UID 1000.

Note that the previous version of Users block where one entry is : "<username>" : ["user-id", "password"], continues to be supported to only add users for backward compatibility but not to update users.

Example(s)

"Users": {

"one": {

"UID": "1001",

"Username" : "nvidia2",

"Password": "driveos"

},

"two": {

"UID": "1002",

"Username" : "nvidia3",

"Password": {

"HashedPassword": "$6$4bhqDdYb$kxJApfqarvpuMhLweydYp7

.NqSFXWxML8N3JywqadmlEp9GF89553PNBAYBTdGmfBaUe7/7LxpP8PBBQlCJT70"

},

}

Field

Groups

Type

Object

Acceptable Values

Key content: Unique user identification alphanumeric string

Value type: dict

Value content:

{

??? "<key >": {

"GID" : "<Group-Identifier in target /etc/group>" (String) (Required),

"Groupname" : "<Group name in target /etc/group>", (String) (Required)

}

or

Key content: Valid UNIX groupname

Value type: String

Value content: Valid UNIX group identifier

The latter entry is just for legacy support and not recommended to be used.

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more groups to be added to the target filesystem.

For each key-value pair in the JSON, a group is described by its attributes: groupname and the group-identifier. This entry will either add or update the group as described by workflow below. Ordering of groups to be added is preserved.

Ensure group names and group identifiers are valid UNIX standards.

Group identifier is recommended to be above 1000, and not conflicting with existing group identifiers; otherwise, conflicting user identifiers will be reported as an error.

Workflow:

Build-FS fetches the group entry's GID attribute in the CONFIG file and then checks if there exists a group whose identifier matches value of GID in the filesystem described by -f option or "Base" .

If the group exists, Build-FS updates the groupname of that account to what is specified in the group entry of the CONFIG file.

If the group does not exist, Build-FS proceeds to add the group with the groupname provided in the group entry of the CONFIG file.

Note that the previous version of Groups block where one entry is: "<groupname>": "<group-id>", continues to be supported to only add groups for backward compatibility but not to update groups.

Example(s)

"Groups": {

"one": {

"Groupname": "automotive",

"GID": "2001"

}

Field

Memberships

Type

Object

Acceptable Values

Key content: valid UNIX username

Value type: Array

Value content: [ group1(String),...., groupN(String) ]

Where group* must be a valid UNIX groupname or group identifier.

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more group memberships to be added to the target filesystem.

Example(s)

"Memberships":

{

??? "nvidia":

???? [

??????? "1000",

??????? "audio",

??????? "cdrom",

??????? "dialout",

??? ]

}

Field

DebianPackages

Type

Array

Acceptable Values

Items type: String

Items content: Valid Debian package names.

Req

No

Default

None

Instructions

Specifies a list of zero, one, or more Debian packages to be installed on target filesystem during Build stage.

Each Debian package can be accompanied by a valid corresponding package version but is entirely optional. If no package version is specified, the latest version as reported by the Debian mirror will be acquired and installed

If the list of Debians and or the specified versions conflict, an error will be reported.

Example(s)

" DebianPackages ":

[

??? "openssh-server=1-4ubuntu0.3",

??? "vim"

]

Field

Hostname

Type

String

Acceptable Values

Valid UNIX hostname

Req

No

Default

None

Instructions

Host name of the target filesystem is updated to the one specified as the value for HostName.

If HostName Field is not present in the CONFIG, the host name of the Base filesystem is preserved.

Example(s)

"HostName": "auto-ubuntu"

Field

Mount

Acceptable Values

Value type: array{

"<Path of mount point> (Required) (String)":
                           {

"Type": "<Type of the Linux Filesystem to be mounted> (Required)
      (String)",

"MountOptions":
                           "<Mount specific options> (Required)
                           (String)",

"Device": "<Path to the device node or the partition to mount> (Required)
        (String)"

},}

The values to the Mounts Field is an array of dictionaries. Each dictionary entry's key is
        the path to the Mount point which the directory the mount the storage device or the
        partition.

The dictionary entry's value following the key is the dictionary of 3 key-value pairs where
        keys are {"Type", "MountOptions", "Device"}.

The Type is the filesystem type such as ext4, ext3, ext2, nfs, overlayfs, ubifs and so
        on.

MountOptions are the comma-separated specific mount options as required. If no specific
        options are required, it must be assigned as "defaults".

Device is the path to the device node of the partition that contains the filesystem in Type
        and must be mounted on the mount-point (referred above) with the options from
        MountOptions.

Req

No

Default

None

Instructions

The Mounts entry recorded in Build-FS config is used to generate an /etc/fstab entry and append it to be filesystem's /etc/fstab in the same order as listed in the Mounts block. The block must be populated only when the user is sure of the partition/device in Device contains the filesystem of Type. Entering a Mounts entry without an existing filesystem in the Device leads to a mount error during the filesystem runtime.

Example(s)

"Mounts": { "/home/": {

"Type":
                        "ext4",

"MountOptions":
                        "defaults",

"Device":
                        "/dev/vblkdev3"

},}

This example mounts the ext4 filesystem in /dev/vblkdev3 at /home/ with default
        options.

Field

FilesystemInclude

Acceptable Values

Value type:
                        array

{ ...,

"<Path to file
                        to be included> (Required) (String)",

...,

"<Path to
                        directory to be included>/ (Required) (String)",

...}

The FilesystemInclude block contains the subset of files and directory to be chosen from
        the Build-FS filesystem working directory after building the filesystem content. The block
        is optional and if it is absent, the entire Build-FS filesystem working directory goes into
        the filesystem image. The path to files and the path to directories slightly differ because
        the path to directory always must end with a slashs to indicate a directory where as the
        path of a file must not end with a slash.

The list of paths required must be expressed in absolute path directory in the Build-FS
        config or defined using intermediate environment variables and in such cases the environment
        must define variable.

Default

None

Instructions

The FilesystemInclude block applies when user wishes to copy only a subset of data from filesystem work directory to the final image. However, if the user wants the entire content in the workspace, FilesystemInclude block must to be used.

Example(s)

"FilesystemInclude": [ "/etc/group", "/etc/gshadow", "/etc/passwd", "/etc/shadow", "/etc/subgid", "/etc/subuid", "/etc/passwd", "/home/" ],

This example ensures the files listed (until and excluding /home) are chosen along with
        /home/ directory and its contents are the subset of data that shall be part of the Build-FS
        created filesystem image.

Field

AssociatedFilesystems

Acceptable Values

Value type:
                        array

{ ...

"<Path to build-fs CONFIG associated with the parent CONFIG OR base filename of build-fs
        CONFIG> (Required) (String)",

"<Path to build-fs CONFIG associated with the parent CONFIG OR base filename of build-fs
        CONFIG> (Required) (String)",

...}

Req

No

Default

None

Instructions

The Build-FS CONFIG in AssosciatedFilesystems block can either be an entry to the absolute path of the CONFIG file or just a filename. If it is a filename, then Build-FS looks for the CONFIG in Associated Filesystems in the parent CONFIG's directory.

The Build-FS CONFIG in AssosciatedFilesystems block is a valid Build-FS config (no different than the associator's CONFIG). In fact, each CONFIG in the AssociatedFilesystems can be executed as dedicated instances of Build-FS. The AssociatedFilesystems block can be applied recursively such that the Build-FS CONFIG within the AssociatedFilesystems can request more AssociatedFilesystems. Finally, the fields within CONFIG of AssociatedFilesystems are not flattened into the parent Build-FS CONFIG's MANIFEST but instead each CONFIG in ASsociatedFilesystems creates its corresponding MANIFEST.

Example(s)

"AssociatedFilesystems":
                        [

"driveos-core-rfs-user-metadata.CONFIG.json", "${BUILD_FS_DIR}/configs/driveos-core-rfs-user-data.CONFIG.json" ],

This example the first associated filesystem shall be located at the same directory as the
        parent's CONFIG whereas the final CONFIG must be present at the full path
        "${BUILD_FS_DIR}/configs/driveos-core-rfs-user-data.CONFIG.json".

Field

SELinux

Acceptable Values

Value type: dict

Value
                        content:

{

"SetFiles": <Path to the 3rdparty SELinux setfiles application> (String)
      (Required),

"PolicyFile": <Path to the SELinux policy binary file> (String)
      (Required),

"ContextFile":
                        <Path to SELinux context file> (String)
                        (Required)

}

The value is of type dictionary but the set of keys in the directionary is fixed to
        {"SetFiles", "PolicyFile", "ContextFile"}.

The SetFiles key holds the absolute path to host-side setfiles application. This
        application is provided Ubuntu host-side package check policycoreutils.

The PolicyFile key holds the absolute path to the SELinux precompiled policy binary file
        (built using checkpolicy application).

The
                        ContextFile key holds the absolute path to SELinux context
                     file.

For more information on SELinux policy and SELinux context file, please refer to DRIVE OS
        LINUX SELinux documentation.

Req

No

Default

None

Instructions

The SELinux block specifies the required inputs for build-fs to apply appropriate the SELinux attributes (SELinux attributes is a part of extended attributes of a file or a directory). SELinux block is a dictionary but Build-FS only supports and requires 3-fixed keys {"SetFiles", "PolicyFile", "ContextFile"}. The value of each of the keys must the respective absolute paths. Build-FS supports specifying the paths using environment variables only if such variables are defined the Build-FS environment file.

For DRIVE OS LINUX, the setfiles application can be obtained by installing policycoreutils package via apt-get. Then, the app resides at path /sbin/setfiles. The workflow of editing policy and context file is documented in DRIVE OS LINUX SELINUX documentation.

Example(s)

1) Explcit path to each of the
                        entries.

"SELinux": { "SetFiles": "/sbin/setfiles",

"PolicyFile":
        "${NV_WORKSPACE}/drive-linux/filesystem/contents/configs/selinux/policy.30",

"ContextFile":
        ${NV_WORKSPACE}/drive-linux/filesystem/contents/configs/selinux/file_contexts"}

2)
                        Paths can be defined using build-FS environment
                        variable

"SELinux": {

"SetFiles":
                        "${SELINUX_SETFILES_PATH}",

"PolicyFile":
                        "${SELINUX_POLICY_PATH}",

"ContextFile":
                        "${SELINUX_CONTEXT_PATH}"

}

The build-FS
                        environment would contain the expansion of the
                        variables:

{...

"SDKPLATDIR":
                        "${NV_WORKSPACE}/drive-linux",

"SELINUX_SETFILES_PATH":
                        "/sbin/setfiles",

"SELINUX_POLICY_PATH":
        "${SDKPLATDIR}/filesystem/contents/configs/selinux/policy.30",

"SELINUX_CONTEXT_PATH":
        "${SDKPLATDIR}/filesystem/contents/configs/selinux/file_contexts",

...}