NATS is a lightweight messaging protocol used to publish/subscribe OpenFMB profiles to/from a NATS server.
NATS uses a topic hierarchy delimited by periods. Within the context of OpenFMB, the topic name takes the following form:
openfmb.<module name>.<profile name>.<subject name>
<subject name> may be a the
* wildcard or the ConductingEquipment
mRID. All messages published to the NATS server will use the fully qualified
topic name including the mRID.
|max-queued-messages||Number of messages to keep in the publishing queue before discarding the oldest.|
|connect-url||Connection address of the NATS server. The protocol can be |
|connect-retry-seconds||Number of seconds to wait before trying to re-establish a connection to the server.|
|publish||List of profiles to publish to NATS server (from the internal bus to NATS)|
|subscribe||List of profiles to subscribe from the NATS server (from NATS to the internal bus)|
subscribe section specify lists of profiles, the profile name (
profile), and which equipment you want to publish/subscribe to (
subject). The subject name can either be
* to publish/subscribe to all the
profiles, or a specific ConductingEquipment mRID.
The connection to a NATS server may optionally be secured using TLS.
The required contents of the
security section depends on the value of
If no security is needed, the
security-type can be set to
To learn how to produce self-signed certificates with OpenSSL, check Self-signed certificates.
In this mode, the client authenticates the server using a certificate, and then the server authenticates the client using a username and password sent over the encrypted TLS channel.
Authorization for each user can be specified in the config file of the NATS server. See this page for more details.
The server must run with a TLS certificate, a username and a password in this mode:
The Adapter is configured to authenticate the server using a trusted root certificate or self-signed certificate of the broker. The username and the password are embedded in the connection URL.
In this mode, the client and the server mutually authenticate one another using certificates.
The server must run with a TLS certificate and must validate the client certificate.
The Adapter is configured to perform mutual authentication and is provided with the paths to the server certificate, the client's private key, and a certificate chain file that, at a minimum, contains the client's self-signed certificate.
The username/password is not required when using TLS mutual authentication, but the two modes are not mutually exclusive, either. You can do server-only authentication without any credentials (client not authenticated), and you can require username/password server-side even with TLS mutual authentication.
A NATS client can prove its permission to the server by providing a JSON Web Token (JWT). It is possible to specify the token with the
parameter. This feature can be used alone, with server-only authentication, or with mutual authentication.
Using JWT only ensures that the client has permissions attested to with the token. It does not protect the communications from tampering or inspection in the same way that TLS does.
The NATS server must be configured to authenticate the JWT with the appropriate key and know all the accounts that exist.
To statically list all the accounts, run the following:
It will generate a
auth.conf similar to this:
Simply include it in the NATS main config file:
A ready-to-use HTTP account resolver is available.
In the NATS config file, add the following lines: