config.json

// Note: C++/JavaScript-style single and multi-line comments are permitted and ignored in nmos-cpp config files

// Configuration settings and defaults
{
    // Custom settings for the example node implementation

    // node_tags, device_tags: used in resource tags fields
    // "Each tag has a single key, but MAY have multiple values."
    // See https://specs.amwa.tv/is-04/releases/v1.3.2/docs/APIs_-_Common_Keys.html#tags
    // {
    //     "tag_1": [ "tag_1_value_1", "tag_1_value_2" ],
    //     "tag_2": [ "tag_2_value_1" ]
    // }
    //"node_tags": {},
    //"device_tags": {},

    // how_many: provides for very basic testing of a node with many sub-resources of each type
    //"how_many": 4,

    // activate_senders: controls whether to activate senders on start up (true, default) or not (false)
    //"activate_senders": false,

    // senders, receivers: controls which kinds of sender and receiver are instantiated by the example node
    // the values must be an array of unique strings identifying the kinds of 'port', like ["v", "a", "d"], see impl::ports
    // for MXL senders and receivers, the values must be like ["xv", "xa", "xd"]
    // when omitted, all ports are instantiated
    //"senders": ["v", "a"],
    //"receivers": [],

    // frame_rate: controls the grain_rate of video, audio and ancillary data sources and flows
    // and the equivalent parameter constraint on video receivers
    // the value must be an object like { "numerator": 25, "denominator": 1 }
    //"frame_rate": { "numerator": 60000, "denominator": 1001 },

    // frame_width, frame_height: control the frame_width and frame_height of video flows
    //"frame_width": 3840,
    //"frame_height": 2160,

    // interlace_mode: controls the interlace_mode of video flows, see nmos::interlace_mode
    // when omitted, a default of "progressive" or "interlaced_tff" is used based on the frame_rate, etc.
    //"interlace_mode": "progressive",

    // colorspace: controls the colorspace of video flows, see nmos::colorspace
    //"colorspace": "BT709",

    // transfer_characteristic: controls the transfer characteristic system of video flows, see nmos::transfer_characteristic
    //"transfer_characteristic": "SDR",

    // color_sampling: controls the color (sub-)sampling mode of video flows, see sdp::sampling
    //"color_sampling": "YCbCr-4:2:2",

    // component_depth: controls the bits per component sample of video flows
    //"component_depth": 10,

    // video_type: media type of video flows, e.g. "video/raw", "video/jxsv" for ST 2110 senders and receivers, see nmos::media_types
    //"video_type": "video/raw",

    // mxl_video_type: media type of MXL video flows and receivers, e.g. "video/v210" or "video/v210a", see nmos/mxl.h
    //"mxl_video_type": "video/v210",

    // channel_count: controls the number of channels in audio sources
    //"channel_count": 8,

    // smpte2022_7: controls whether senders and receivers have one leg (false) or two legs (true, default)
    //"smpte2022_7": false,

    // simulate_status_monitor_activity: when true status monitor statuses will change randomly after activation
    //"simulate_status_monitor_activity": true,

    // Configuration settings and defaults for logging

    // error_log [registry, node]: filename for the error log or an empty string to write to stderr
    //"error_log": "",

    // access_log [registry, node]: filename for the access log (in Common Log Format) or an empty string to discard
    //"access_log": "",

    // logging_level [registry, node]: integer value, between 40 (least verbose, only fatal messages) and -40 (most verbose)
    //"logging_level": 0,

    // logging_categories [registry, node]: array of logging categories to be included in the error log
    //"logging_categories": ["node_implementation"],

    // Configuration settings and defaults for the NMOS APIs

    // host_name [registry, node]: the fully-qualified host name for which to advertise services, also used to construct response headers and fields in the data model
    //"host_name": "", // when omitted or an empty string, the default is used

    // domain [registry, node]: the domain on which to browse for services or an empty string to use the default domain (specify "local." to explictly select mDNS)
    //"domain": "",

    // dns_sd_browse_mode [node]: DNS-SD browse method per TR-10-9 Section 15
    //   both(0) (default) = unicast DNS first, mDNS fallback if unsuccessful
    //   unicast(1)        = unicast DNS only
    //   mdns(2)           = mDNS only
    // Expected resolve behaviour for each (mode, domain) combination:
    //   mode    | domain      | behaviour
    //   --------+-------------+--------------------
    //   both    | example.com | unicast -> mdns
    //   both    | local.      | mdns
    //   unicast | example.com | unicast
    //   unicast | local.      | mdns
    //   mdns    | example.com | mdns
    //   mdns    | local.      | mdns
    //"dns_sd_browse_mode": 0,

    // host_address/host_addresses [registry, node]: IP addresses used to construct response headers (e.g. 'Link' or 'Location'), and host and URL fields in the data model
    //"host_address": "127.0.0.1",
    //"host_addresses": array-of-ip-address-strings,

    // is04_versions [registry, node]: used to specify the enabled API versions (advertised via 'api_ver') for a version-locked configuration
    //"is04_versions": ["v1.2", "v1.3"],

    // is05_versions [node]: used to specify the enabled API versions for a version-locked configuration
    //"is05_versions": ["v1.0", "v1.1"],

    // is07_versions [node]: used to specify the enabled API versions for a version-locked configuration
    //"is07_versions": ["v1.0"],

    // is08_versions [node]: used to specify the enabled API versions for a version-locked configuration
    //"is08_versions": ["v1.0"],

    // is09_versions [registry, node]: used to specify the enabled API versions for a version-locked configuration
    //"is09_versions": ["v1.0"],

    // is10_versions [registry, node]: used to specify the enabled API versions for a version-locked configuration
    //"is10_versions": ["v1.0"],

    // is12_versions [node]: used to specify the enabled API versions for a version-locked configuration
    //"is12_versions": ["v1.0"],

    // pri [registry, node]: used for the 'pri' TXT record; specifying nmos::service_priorities::no_priority (maximum value) disables advertisement completely
    //"pri": 100,

    // highest_pri, lowest_pri [node]: used to specify the (inclusive) range of suitable 'pri' values of discovered Registration and System APIs, to avoid development and live systems colliding
    //"highest_pri": 0,
    //"lowest_pri": 2147483647,

    // authorization_highest_pri, authorization_lowest_pri [registry, node]: used to specify the (inclusive) range of suitable 'pri' values of discovered Authorization APIs, to avoid development and live systems colliding
    //"authorization_highest_pri": 0,
    //"authorization_lowest_pri": 2147483647,

    // discovery_backoff_min/discovery_backoff_max/discovery_backoff_factor [registry, node]: used to back-off after errors interacting with all discoverable service instances
    // e.g. Registration APIs, System APIs, Authorization APIs or OCSP servers
    //"discovery_backoff_min": 1,
    //"discovery_backoff_max": 30,
    //"discovery_backoff_factor": 1.5,

    // service_name_prefix [registry, node]: used as a prefix in the advertised service names ("<prefix>_<api>_<host>:<port>", e.g. "nmos-cpp_node_127-0-0-1:3212")
    //"service_name_prefix": "nmos-cpp"

    // registry_address [node]: IP address or host name used to construct request URLs for registry APIs (if not discovered via DNS-SD)
    //"registry_address": ip-address-string,

    // registry_version [node]: used to construct request URLs for registry APIs (if not discovered via DNS-SD)
    //"registry_version": "v1.2",

    // port numbers [registry, node]: ports to which clients should connect for each API

    // http_port [registry, node]: if specified, this becomes the default port for each HTTP API and the next higher port becomes the default for each WebSocket API
    //"http_port": 0,

    // registration_port [node]: used to construct request URLs for the registry's Registration API (if not discovered via DNS-SD)
    //"registration_port": 3210,
    //"node_port": 3212,
    //"connection_port": 3215,
    //"events_port": 3216,
    //"events_ws_port": 3217,
    //"channelmapping_port": 3215,
    // system_port [node]: used to construct request URLs for the System API (if not discovered via DNS-SD)
    //"system_port": 10641,
    // control_protocol_ws_port [node]: used to construct request URLs for the Control Protocol websocket, or negative to disable the control protocol features
    //"control_protocol_ws_port": 3218,
    //"configuration_port": 3219,

    // listen_backlog [registry, node]: the maximum length of the queue of pending connections, or zero for the implementation default (the implementation may not honour this value)
    //"listen_backlog": 0,

    // registration_heartbeat_interval [registry, node]:
    // "Nodes are expected to peform a heartbeat every 5 seconds by default."
    // See https://specs.amwa.tv/is-04/releases/v1.2.0/docs/4.1._Behaviour_-_Registration.html#heartbeating
    //"registration_heartbeat_interval": 5,

    // registration_request_max [node]: timeout for interactions with the Registration API /resource endpoint
    //"registration_request_max": 30,

    // registration_heartbeat_max [node]: timeout for interactions with the Registration API /health/nodes endpoint
    // Note that the default timeout is the same as the default heartbeat interval, in order that there is then a reasonable opportunity to try the next available Registration API
    // though in some circumstances registration expiry could potentially still be avoided with a timeout that is (almost) twice the garbage collection interval...
    //"registration_heartbeat_max": 5,

    // immediate_activation_max [node]: timeout for immediate activations within the Connection API /staged endpoint
    //"immediate_activation_max": 30,

    // events_heartbeat_interval [node, client]:
    // "Upon connection, the client is required to report its health every 5 seconds in order to maintain its session and subscription."
    // See https://specs.amwa.tv/is-07/releases/v1.0.1/docs/5.2._Transport_-_Websocket.html#41-heartbeats
    //"events_heartbeat_interval": 5,

    // events_expiry_interval [node]:
    // "The server is expected to check health commands and after a 12 seconds timeout (2 consecutive missed health commands plus 2 seconds to allow for latencies)
    // it should clear the subscriptions for that particular client and close the websocket connection."
    // See https://specs.amwa.tv/is-07/releases/v1.0.1/docs/5.2._Transport_-_Websocket.html#41-heartbeats
    //"events_expiry_interval": 12,

    // system_address [node]: IP address or host name used to construct request URLs for the System API (if not discovered via DNS-SD)
    //"system_address": ip-address-string,

    // system_version [node]: used to construct request URLs for the System API (if not discovered via DNS-SD)
    //"system_version": "v1.0",

    // system_request_max [node]: timeout for interactions with the System API
    //"system_request_max": 30,

    // Configuration settings and defaults for experimental extensions

    // seed id [registry, node]: optional, used to generate repeatable id values when running with the same configuration
    //"seed_id": uuid-string,

    // mxl_domain_id [node]: optional, overrides the generated MXL domain id used by MXL sender/receiver transport params
    //"mxl_domain_id": uuid-string,

    // label [registry, node]: used in resource label field
    //"label": "",

    // description [registry, node]: used in resource description field
    //"description": "",

    // port numbers [registry, node]: ports to which clients should connect for each API
    // see http_port

    //"settings_port": 3209,
    //"logging_port": 5106,

    // addresses [registry, node]: IP addresses on which to listen for each API, or empty string for the wildcard address

    // server_address [registry, node]: if specified, this becomes the default address on which to listen for each API instead of the wildcard address
    //"server_address": "",

    // addresses [registry, node]: IP addresses on which to listen for specific APIs

    //"settings_address": "127.0.0.1",
    //"logging_address": "",

    // client_address [registry, node]: IP address of the network interface to bind client connections
    // for now, only supporting HTTP/HTTPS client connections on Linux
    //"client_address": "",

    // logging_limit [registry, node]: maximum number of log events cached for the Logging API
    //"logging_limit": 1234,

    // logging_paging_default/logging_paging_limit [registry, node]: default/maximum number of results per "page" when using the Logging API (a client may request a lower limit)
    //"logging_paging_default": 100,
    //"logging_paging_limit": 100,

    // http_trace [registry, node]: whether server should enable (default) or disable support for HTTP TRACE
    //"http_trace": true,

    // proxy_map [registry, node]: mapping between the port numbers to which the client connects, and the port numbers on which the server should listen, if different
    // for use with a reverse proxy; each element of the array is an object like { "client_port": 80, "server_port": 8080 }
    //"proxy_map": array-of-mappings,

    // proxy_address [registry, node]: address of the forward proxy to use when making HTTP requests or WebSocket connections, or an empty string for no proxy
    //"proxy_address": "127.0.0.1",

    // proxy_port [registry, node]: forward proxy port
    //"proxy_port": 8080,

    // href_mode [registry, node]: whether the host name (1), addresses (2) or both (3) are used to construct response headers, and host and URL fields in the data model
    //"href_mode": 1,

    // client_secure [registry, node]: whether clients should use a secure connection for communication (https and wss)
    // when true, CA root certificates must also be configured
    //"client_secure": false,

    // ca_certificate_file [registry, node]: full path of certification authorities file in PEM format
    // on Windows, if C++ REST SDK is built with CPPREST_HTTP_CLIENT_IMPL=winhttp (reported as "client=winhttp" by nmos::get_build_settings_info)
    // the trusted root CA certificates must also be imported into the certificate store
    //"ca_certificate_file": "ca.pem",

    // server_secure [registry, node]: whether server should listen for secure connection for communication (https and wss)
    // e.g. typically false when using a reverse proxy, or the same as client_secure otherwise
    // when true, server certificates etc. must also be configured
    //"server_secure": false,

    // server_certificates [registry, node]: an array of server certificate objects, each has the name of the key algorithm, the full paths of private key file and certificate chain file
    // each value must be an object like { "key_algorithm": "ECDSA", "private_key_file": "server-ecdsa-key.pem", "certificate_chain_file": "server-ecdsa-chain.pem" }
    // key_algorithm (attribute of server_certificates objects): name of the key algorithm for the certificate, see nmos::key_algorithm
    // private_key_file (attribute of server_certificates objects): full path of private key file in PEM format
    // certificate_chain_file (attribute of server_certificates object): full path of certificate chain file in PEM format, which must be sorted
    // starting with the server's certificate, followed by any intermediate CA certificates, and ending with the highest level (root) CA
    // on Windows, if C++ REST SDK is built with CPPREST_HTTP_LISTENER_IMPL=httpsys (reported as "listener=httpsys" by nmos::get_build_settings_info)
    // one of the certificates must also be bound to each port e.g. using 'netsh add sslcert'
    //"server_certificates": [{"key_algorithm": "ECDSA", "private_key_file": "server-ecdsa-key.pem", "certificate_chain_file": "server-ecdsa-chain.pem"}, {"key_algorithm": "RSA", "private_key_file": "server-rsa-key.pem", "certificate_chain_file": "server-rsa-chain.pem"}],

    // validate_certificates [registry, node]: boolean value, false (ignore all server certificate validation errors), or true (do not ignore, the default behaviour)
    //"validate_certificates": true,

    // dh_param_file [registry, node]: Diffie-Hellman parameters file in PEM format for ephemeral key exchange support, or empty string for no support
    //"dh_param_file": "dhparam.pem",

    // system_interval_min/system_interval_max [node]: used to poll for System API changes; default is about one hour
    //"system_interval_min": 3600,
    //"system_interval_max": 3660,

    // hsts_max_age [registry, node]: the HTTP Strict-Transport-Security response header's max-age value; default is approximately 365 days
    // (the header is omitted if server_secure is false, or hsts_max_age is negative)
    // See https://tools.ietf.org/html/rfc6797#section-6.1.1
    //"hsts_max_age": 31536000,

    // hsts_include_sub_domains [registry, node]: the HTTP Strict-Transport-Security HTTP response header's includeSubDomains value
    // See https://tools.ietf.org/html/rfc6797#section-6.1.2
    //"hsts_include_sub_domains": false,

    // ocsp_interval_min/ocsp_interval_max [registry, node]: used to poll for certificate status (OCSP) changes; default is about one hour
    // Note that if half of the server certificate expiry time is shorter, then the ocsp_interval_min/max will be overridden by it
    //"ocsp_interval_min": 3600,
    //"ocsp_interval_max": 3660,

    // ocsp_request_max [registry, node]: timeout for interactions with the OCSP server
    //"ocsp_request_max": 30,

    // authorization_address [registry, node]: IP address or host name used to construct request URLs for the Authorization API (if not discovered via DNS-SD)
    //"authorization_address": ip-address-string,

    // authorization_port [registry, node]: used to construct request URLs for the authorization server's Authorization API (if not discovered via DNS-SD)
    //"authorization_port" 443,

    // authorization_version [registry, node]: used to construct request URLs for Authorization API (if not discovered via DNS-SD)
    //"authorization_version": "v1.0",

    // authorization_selector [registry, node]: used to construct request URLs for the authorization API (if not discovered via DNS-SD)
    //"authorization_selector", "",

    // authorization_request_max [registry, node]: timeout for interactions with the Authorization API /certs & /token endpoints
    //"authorization_request_max": 30,

    // fetch_authorization_public_keys_interval_min/fetch_authorization_public_keys_interval_max [registry, node]: used to poll for Authorization API public keys changes; default is about one hour
    // "Resource Servers (Nodes) SHOULD seek to fetch public keys from the Authorization Server at least once every hour. Resource Servers MUST vary their retrieval
    // interval at random by up to at least one minute to avoid overloading the Authorization Server due to Resource Servers synchronising their retrieval time."
    // See https://specs.amwa.tv/is-10/releases/v1.0.0/docs/4.1._Behaviour_-_Authorization_Servers.html#authorization-server-public-keys
    //"fetch_authorization_public_keys_interval_min": 3600,
    //"fetch_authorization_public_keys_interval_max": 3660,

    // access_token_refresh_interval [node]: time interval (in seconds) to refresh access token from Authorization Server
    // It specified the access token refresh period otherwise Bearer token's expires_in is used instead.
    // See https://specs.amwa.tv/is-10/releases/v1.0.0/docs/4.4._Behaviour_-_Access_Tokens.html#access-token-lifetime
    //"access_token_refresh_interval": -1,

    // client_authorization [node]: whether clients should use authorization to access protected APIs
    //"client_authorization": false,

    // server_authorization [registry, node]: whether server should use authorization to protect its APIs
    //"server_authorization": false,

    // authorization_code_flow_max [node]: timeout for the authorization code flow (in seconds)
    // No timeout if value is set to -1, default to 30 seconds
    //"authorization_code_flow_max": 30,

    // authorization_flow [node]: used to specify the authorization flow for the registered scopes
    // supported flow are authorization_code and client_credentials
    // client_credentials SHOULD only be used for NO user interface node, otherwise authorization_code MUST be used
    //"authorization_flow": "authorization_code",

    // authorization_redirect_port [node]: redirect URL port for listening authorization code, used for client registration
    //"authorization_redirect_port": 3218,

    // initial_access_token [node]: initial access token giving access to the client registration endpoint for non-opened registration
    //"initial_access_token", "",

    // authorization_scopes [node]: used to specify the supported scopes for client registration
    // supported scopes are registration, query, node, connection, events and channelmapping
    //"authorization_scopes": [ "registration" ],

    // token_endpoint_auth_method [node]: String indicator of the requested authentication method for the token endpoint
    // supported methods are none, client_secret_basic and private_key_jwt, default to client_secret_basic, where none is used for public client
    // when using private_key_jwt, the JWT is created and signed by the node's private key
    //"token_endpoint_auth_method": "client_secret_basic",

    // jwks_uri_port [node]: JWKs URL port for providing JSON Web Key Set (public keys) to Authorization Server for verifing client_assertion, used for client registration
    //"jwks_uri_port": 3218,

    // validate_openid_client [node]: boolean value, false (bypass openid connect client validation), or true (do not bypass, the default behaviour)
    //"validate_openid_client": true,

    // no_trailing_dot_for_authorization_callback_uri [node]: used to specify whether no trailing dot FQDN should be used to construct the URL for the authorization server callbacks
    // as it is because not all Authorization server can cope with URL with trailing dot, default to true
    //"no_trailing_dot_for_authorization_callback_uri": true,

    // retry_after [registry, node]: used to specify the HTTP Retry-After header to indicate the number of seconds when the client may retry its request again, default to 5 seconds
    // "Where a Resource Server has no matching public key for a given token, it SHOULD attempt to obtain the missing public key via the the token iss
    // claim as specified in RFC 8414 section 3. In cases where the Resource Server needs to fetch a public key from a remote Authorization Server it
    // MAY temporarily respond with an HTTP 503 code in order to avoid blocking the incoming authorized request. When a HTTP 503 code is used, the Resource
    // Server SHOULD include an HTTP Retry-After header to indicate when the client may retry its request.
    // If the Resource Server fails to verify a token using all public keys available it MUST reject the token."
    //"service_unavailable_retry_after": 5,

    // manufacturer_name [node]: the manufacturer name of the NcDeviceManager used for NMOS Control Protocol
    // See https://specs.amwa.tv/ms-05-02/branches/v1.0.x/docs/Framework.html#ncdevicemanager
    //"manufacturer_name": "",

    // product_name/product_key/product_revision_level [node]: the product description of the NcDeviceManager used for NMOS Control Protocol
    // See https://specs.amwa.tv/ms-05-02/branches/v1.0.x/docs/Framework.html#ncproduct
    //"product_name": "",
    //"product_key": "",
    //"product_revision_level": "",

    // serial_number [node]: the serial number of the NcDeviceManager used for NMOS Control Protocol
    // See https://specs.amwa.tv/ms-05-02/branches/v1.0.x/docs/Framework.html#ncdevicemanager
    //"serial_number": "",

    "don't worry": "about trailing commas"
}