Optional CONFIG Fields

Base

String

Valid UNIX dirpath or a Valid UNIX filepath.

No

None

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:

1. A folder
2. A mountable image file with the extension .img in the filename
3. 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.

"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"

PreInstalls

Object

Key content: Valid UNIX filepath to a BASH script.

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

No

None

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.

" PreInstalls ":

{

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

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

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

}

CopyTargets

Array

No

None

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.

PostInstalls

Object

Key content: Valid UNIX filepath to a BASH script.

Value type: String

Value content: enum[host, target, target_copy]

No

None

"PostInstalls":

{

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

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

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

}

FilesystemCleanup

Array

Items type: String

Items content: Valid UNIX filepaths

No

None

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

" FilesystemCleanup ":

[

    "/tmp/temp.txt",

    "/var/tmp/tmp.log"

]

ImageSize

String

64-bit Unsigned Integer enclosed in double quotes.

No

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.

"ImageSize": "4294967296"

FilesystemType

String

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

No

standard

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.

"FilesystemType": "standard"

Mirrors

Array

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)

}

No

None

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.

"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"}

]

Users

Object

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.

No

None

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.

"Users": {

"one": {

"UID": "1001",

"Username" : "nvidia2",

"Password": "driveos"

},

"two": {

"UID": "1002",

"Username" : "nvidia3",

"Password": {

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

.NqSFXWxML8N3JywqadmlEp9GF89553PNBAYBTdGmfBaUe7/7LxpP8PBBQlCJT70"

},

}

Groups

Object

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.

No

None

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.

"Groups": {

"one": {

"Groupname": "automotive",

"GID": "2001"

}

}

Memberships

Object

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.

No

None

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

"Memberships":

{

    "nvidia":

     [

        "1000",

        "audio",

        "cdrom",

        "dialout",

    ]

}

DebianPackages

Array

Items type: String

Items content: Valid Debian package names.

No

None

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.

" DebianPackages ":

[

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

    "vim"

]

Hostname

String

Valid UNIX hostname

No

None

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.

"HostName": "auto-ubuntu"