Package Format

NAS OS apps are distributed under the form of package files. The packages have the extension .rbw, named after the NAS OS SDK tool rainbow. A .rbw file is an uncompressed TAR archive with the following content:

Packages files are named as follows:

<package_id>-<package_version>-<package_architecture>.rbw

An example would be:

com.mycompany.myapp-1.0-x86_64.rbw

Metadata

The package.json file is a JSON file that contains the package’s metadata. You will find below a detailed description of each supported field.

id

• Type: string
• Mandatory: yes
• Description: The unique identifier for the app
• Supported characters: Lowercase letters, digits, “_” and “-“.
• Constraints: It has to be formed as 3 strings, separated by dots and start with a letter.
• Example value:

{
    "id": "com.seagate.my_app"
}

version

• Type: string
• Mandatory: yes
• Description: The app’s version
• Supported characters: digits and dots
• Constraints: has to start and end with a digit
• Example value:

{
    "version": "1.2.3"
}

architecture

• Type: string
• Mandatory: yes
• Description: The app’s architecture
• Supported values:

{
    "type": "x86_64"
}

{
    "type": "armv5"
}

{
    "type": "armv7"
}

• Default value:

{
    "type": "x86_64"
}

type

• Type: string
• Mandatory: yes
• Description: The package’s type
• Supported values:

{
    "type": "application"
}

{
    "type": "container"
}

{
    "type": "utility"
}

• Default value:

{
    "type": "application"
}

depends

• Type: array of strings
• Mandatory: yes
• Description: The list of dependencies for the app. Dependencies are packages of type container or utility and referenced by their ID
• Example value:

{
    "depends": [
        "org.debian.wheezy-lamp-1.2",
        "com.nasos.unicorn_api-5.0.1"
    ]
}

• Default value:

{
    "depends": []
}

conflicts

New in SDK 0.7, requires NASOS ≥ 4.2.

• Type: array of dicts of strings:strings
• Mandatory: no
• Description: A list of apps the app conflicts with. To specify a conflict, you must add a dict with the conflicting app ID as the id key. You can optionally limit the conflict to a given version range by specifying the from and to keys which must contain the version strings delimiting (inclusively) the version range. The same app can be referenced multiple times in order to specify several version ranges.
• Example value:

To specify a conflict for an app older than version 0.9:

{
    "conflicts": [{"id": "com.vendor.conflicting_app", "to": "0.9"}]
}

To specify a conflict for an app regardless of versions:

{
    "conflicts": [{"id": "com.vendor.conflicting_app"}]
}

To specify a conflict for an app with a given version 1.5:

{
    "conflicts": [{"id": "com.vendor.conflicting_app", "from": "1.5", "to": "1.5"}]
}

To specify a conflict for an app between versions 0.1 and 0.5 and between versions 0.8 and 0.9:

{
    "conflicts": [
        {"id": "com.vendor.conflicting_app", "from": "0.1", "to": "0.5"},
        {"id": "com.vendor.conflicting_app", "from": "0.8", "to": "0.9"}
    ]
}

• Default value:

{
    "conflicts": []
}

network_ports

• Type: dict of strings:integers
• Mandatory: no
• Description: The network ports required by the app. The key is the port name and the value the requested port number
• Example value:

{
    "network_ports": {
        "WEB_UI": 8080,
        "DOWNLOAD": 1234,
        "UPLOAD": 4567
    }
}

• Default value:

{
    "network_ports": {}
}

fixed_ports

• Type: array of strings
• Mandatory: no

• Description: The list of port names for which a fixed value is mandatory. The names must match those defined in the network_ports setting. At run/install time, if the port value requested in the networt_ports setting isn’t available, an error will be raised instead of a new value being assigned

• Example value:

{
    "fixed_ports": [
        "DOWNLOAD",
        "UPLOAD"
    ]
}

• Default value:

{
    "fixed_ports": []
}

port_mapping

• Type: array of strings
• Mandatory: no

• Description: The list of ports to enable for port mapping redirections. The names must match those defined in the network_ports setting. When a port is listed here, it will be configured for UPNP-IGD and NAT-PMP redirection, enabling WAN access.

• Example value:

{
    "port_mapping": [
        "UPLOAD"
    ]
}

• Default value:

{
    "port_mapping": []
}

settings

• Type: dict of strings:strings
• Mandatory: no
• Description: The package’s settings used to specify details about the app. For example, instead of hard-coding a value in a build script, you can store a value here and access it from the build script as an environment variable using the prefix $RAINBOW_
• Example value:

{
    "settings": {
        "my_custom_setting": "my_custom_value"
    }
}

The setting will be available as $RAINBOW_MY_CUSTOM_SETTING

• Default value:

{
    "settings": {}
}

startup_mode

• Type: string
• Mandatory: no
• Description: Determines if the app is automatically started upon system boot, or manually by the user
• Supported values:

{
    "startup_mode": "auto"
}

{
    "startup_mode": "manual"
}

• Default value:

{
    "startup_mode": "auto"
}

display_mode

• Type: string
• Mandatory: no
• Description: Determines how the app will be displayed in the NAS OS App Board
• Supported values:

To open the app in a new tab:

{
    "display_mode": "tab"
}

To embed the app in an iframe inside the NAS OS App Board:

{
    "display_mode": "embedded"
}

• Default value:

{
    "display_mode": "tab"
}

redirect_mode

• Type: string
• Mandatory: no
• Description: Determines whether the app will be accessed through a reverse proxy or a simple redirection
• Supported values:

To enable the reverse proxy, use the following mode:

{
    "redirect_mode": "transparent"
}

The app can be accessed with the URL http:///apps/

For a simple redirection, use:

{
    "redirect_mode": "custom"
}

The URL can be customized using the redirect_protocol and redirect_path settings

• Default value:

{
    "redirect_mode": "transparent"
}

redirect_protocol

• Type: string
• Mandatory: no
• Description: When redirect_mode is custom, the app can configure the protocol as part of its URL
• Supported values:

{
    "redirect_protocol": "http"
}

{
    "redirect_protocol": "https"
}

• Default value:

{
    "redirect_protocol": "http"
}

redirect_path

• Type: string
• Mandatory: no

• Description: When redirect_mode is custom, the app can configure its path as part of the URL: http://<nas_ip>:<web_ui>/<redirect_path>

• Example value:

{
    "redirect_path": "my_custom_path"
}

user_data_access

• Type: boolean
• Mandatory: no
• Description: Defines if the app has access to the NAS shares. When true, every share will be available to the app under the /shares/ path
• Supported values:

{
    "user_data_access": true
}

{
    "user_data_access": false
}

• Default value:

{
    "user_data_access": true
}

private_data_access

• Type: boolean
• Mandatory: no
• Description: When true, a dedicated storage space will be available to the app under the /data/ path
• Supported values:

{
    "private_data_access": true
}

{
    "private_data_access": false
}

• Default value:

{
    "private_data_access": false
}

app_data

• Type: array of strings
• Mandatory: no

• Description: The list of paths the app uses for its configuration or internal data. It is the data kept during an update. It can be a list of directories and files that use simple wild cards

• Example value:

{
    "app_data": [
        "/etc/my_app.config",
        "/var/lib/my_app/",
        "/var/log/my_app*.log"
    ]
}

nasos_min_version

• Type: string
• Mandatory: no

• Description: The minimum NAS OS version for which the app is known to be compatible. The syntax is the same as the version field. The system must have a version greater or equal than nasos_min_version. If no value is specified, the app is considered compatible with every past NAS OS version. Generally this field should match the NAS OS version associated with the SDK version the app was developped with (see Supported NAS Devices)

• Example value:

{
    "nasos_min_version": "4.0.1"
}

nasos_max_version

• Type: string
• Mandatory: no
• Description: The maximum NAS OS version for which the app is known to be compatible. The syntax is the same as the version field. The system must have a version lower or equal than nasos_max_version. If no value is specified, the app is considered compatible with every future NAS OS version.
• Example value:

{
    "nasos_max_version": "4.2.1"
}

registered_events

• Type: array of strings
• Mandatory: no

• Description: The list of NAS OS events that the app is registered for

• Example value:

{
    "registered_events": [
        "volume.post_insert",
        "volume.post_update",
        "volume.pre_delete"
    ]
}

events

• Type: array of strings:dict
• Mandatory: no
• Description: Specifications of events that the app is able to send to the NAS OS system. This section contains a list of dicts, each defining an event, with the following properties:
  • name: the name of the event
  • args: the argument list of the events. For each argument a list of 2 elements containing the argument name and its type is expected:

    {
        "events": [
            {
            "name": "<event_name>",
                "args": [
                    ["<arg1_name>", "<arg1_type>"],
                    ["<arg2_name>", "<arg2_type>"]
                ]
            }
        ]
    }

Supported argument types are:

• unicode: for string values
• int: for integer values

You can also specify a list by appending an * to the type specifier:

• unicode*: for a list of string values

• int*: for list integer values

• Example value:

{
    "events": [
        {
            "name": "my_event",
            "args": [
                ["my_string", "unicode"],
                ["my_integer", "int"],
                ["my_strings", "unicode*"],
                ["my_integers*", "int*"]
            ]
        }
    ]
}

ra_compliant

• Type: boolean
• Mandatory: no

• Description: Defines is the app is compatible with the NASOS Remote Access feature. If the app has any issue while being accessed through remote access, set this to false

• Example value:

{
    "ra_compliant": false
}

https_compliant

• Type: boolean
• Mandatory: no

• Description: Defines is the app is compatible with HTTPS access. If the app has any issue while being accessed through HTTPS, set this to false

• Example value:

{
    "https_compliant": false
}