2.1.2.1 Constant Memory Demand

YANGcore has a constant memory demand that grows in proportion to configuration data.

YANGcore reduces configuration data both passively and actively:

• Passively, YANGcore’s data model is highly normalized³, thus elimanating the need for redundant definitions.

• Actively, binary/base64 values, not needed for YANG-validation, are converted to zero-byte values in memory. This is notable as the binary values tend to be large to very large in size.

2.1.2.2 Transitive Memory Demand

YANGcore has transitive memory demands when processing requests from clients. The highest memory-impacting request is a “PUT” request used to replace the entire YANGcore configuration. In this case, the transitive memory demand is proportional to the sum of the old and new configuration sizes.

2.3.1.1 APIs

Each listening port must specify which “interface” it presents. YANGcore defines interface as follows:

1. The “native” Interface

   The native interface presents an API enabling “northbound” clients to configure everything and anything that can be configured.

   There must always be extacly one “native” interface configured. The default listening port described in Defaults illustrates the “native” interface.

2.3.1.2 HTTP vs HTTPS

Each listening port must be configured to present the “HTTP” or “HTTPS” protocol. The default listening port described in Defaults presents the “HTTP” protocol.

When configured to use “HTTPS”, the YANGcore process terminates the TLS connections itself. By contrast, when configured to use “HTTP”, it is expected that an external endpoint (e.g., an HTTP proxy, such as NGINX) positioned in front of YANGcore will terminate the TLS connections.

Terminating TLS connections outside of YANGcore offloads some CPU load, which may improve performance.

When “HTTP” is used, YANGcore may be additionally configured with information about the external endpoint so that, e.g., when YANGcore sends callback information to remote peers, such as the hyperlinks in account-activation emails, it can address the URLs to the external endpoint instead of YANGcore’s local endpoint.

When “HTTP” is used, it is necessary for the external endpoint to send the client’s certificate in an HTTP header field called “X-Client-Cert” containing a url-encoded PEM. For instance, using NGINX, this is accomplished using the configuration line:

proxy_set_header X-Client-Cert $ssl_client_escaped_cert;"

2.3.2.1 Verifying certificate paths

YANGcore may need to verify certificate paths for the following reasons:

• Verifying a remote server’s certificate.
• Verifying certificate-based client credentials.

In order to properly verify certificate paths, it is sometimes necessary for YANGcore to check the current revocation status of certificate paths. Each certificate may specify URIs for where the CRL or OCSP can be obtained and, when needed, YANGcore will initiate a connection to the URI specified in the certificate.

2.3.2.2 Accessing a remote database

When configured to use a remote database (see Persistence Selection), YANGcore will initiate connections to the remote database, specified by the URI given on the command line.

While the database is “remote” to the ‘yangcore’ process it could be running on the same machine.

The remote port accessed varies by database and TLS configuration.

2.3.2.3 DNS resolution

When initiating any of the previously discussed outbound connections, the configurations for the remote host may be given as either an IP address or a hostname. When a hostname is provided, YANGcore resolves the hostname to IP addresses using the system configured DNS resolver. Depending on how the DNS resolver is configured, the host system may initiate a connection to a network-based resolver. Traditionally this is a TCP-based connection destined to port 53.

2.5.1.1 In-memory Database

The in-memory database type “persists” all data in memory, which is automatically lost when the ‘yangcore’ process ends. In-memory databases are fast, but demand additional process memory usage proportional to the size of the data stored.

An in-memory database is an excellent choice for development and test efforts, as it automatically disappears when the ‘yangcore’ process ends.

An in-memory database may also have use in a production environment (e.g., in an SDN context) whereby the intent is for the YANGcore instance to be ephemeral, lasting only as long as needed to bootstrap a specific set of devices.

Use of the in-memory database type is specified by the database URL provided on the command line having the form:

sqlite:///:memory:

2.5.1.2 File-based Database

The file-based database storage persists all the data into a single file located by the path-component in the database URL specified on the command line. File-based databases may be desirable in cases where persistence across power cycles is important and yet dependency on a remote RDBMS is not desirable.

The specified file may reside on a filesystem mounted from a RAID system providing resiliency against disk failures. Care should be to ensure fast and secure access to a remote system (e.g., a NAS or SAN).

The file itself may be backed-up and restored as needed to ensure disaster recovery. If the filesystem does not support taking snapshots while a system is running, it is recommended that the ‘yangcore’ process is either stopped or suspended during the backup operation.

Use of the file-based database type is specified by the database URL provided on the command line having one of the following form:

sqlite:///relative/path/to/yangcore.db     (unix)
sqlite:////absolute/path/to/yangcore.db    (unix)
sqlite:///C:\path\to\yangcore.db        (windows)

2.5.1.3 RDBMS Database

The RDBMS database engine persists all the data into one of several well-known database systems (e.g., MariaDB, Postgres, Oracle, etc.). In theory, YANGcore can use any RDBMS supported by SQLAlchemy, though it is recommended to only use those that YANGcore has been tested against.

Use of an RDBMS database enables large data sets with fast-access to keyed data. Scaling of the database tier supports a variety of performance and availability targets. It is recommended to use database-level encryption to ensure to protection of the YANGcore data at rest.

Use of the RDBMS database type is specified by the database URL provided on the command line having the form:

<engine>://<user>:<passwd>@<host>:<port>/<database-name>

For instance:

   postgresql://yangcore-admin:secret@db.example.com:5432/yangcore-db 
   mysql+pymysql://yangcore-admin:secret@db.example.com:3306/yangcore-db

The RDBMS database may run on the same machine as YANGcore or on another machine. If the database runs on the same machine, it could listen on the loopback address (e.g., 127.0.0.1) on thus not require network protection. However, if the database runs on another machine, even if in a “secure” or private network, it is recommended that the connection to a remote RDBMS is protected by transport level security (TLS), which entails both configuring the RDBMS server to listen for TLS connections and configuring YANGcore to connect to the the RDBMS using TLS.

To direct YANGcore to establish a TLS connection to the RDBMS, the “–cacert” must be specified. This parameter specifies the trust anchor certificate(s) that YANGcore must use to authenticate the RDBMS’s end entity certificate. For example:

$ yangcore --cacert db-cacert.pem postgresql://user:pass@localhost:5432/yangcore

To direct YANGcore to authenticate itself to the RDBMS using a client certificate, the “–key” and “–cert” parameters must be specified. Note that these parameters must be specified in conjunction with the previously mentioned “–cacert” parameter. For instance:

[Note: '\' line endings per RFC 8792]

$ yangcore --cacert db-cacert.pem --key db-client-key.pem -cert db-client-cert.pem \
postgresql://user:pass@localhost:5432/yangcore

RDBMS-specific details are provided in the RDBMS Configuration section.

2.5.2.1 Prompting for Contract Acceptance

Example output:

<Non-Production Use Contract>

First time initialization. Please accept the license terms.

By entering "Yes" below, you agree to be bound to the terms and conditions contained on this screen with Watsen Networks.

Please enter "Yes" or "No": <YANGcore waits for input here>

Entering “Yes” allows YANGcore to proceed. YANGcore will exit for any other entered response, not just “No”.

Alternatively, the “YANGCORE_ACCEPT_CONTRACT” environment variable may be used to accept the contract. For instance:

$ export YANGCORE_ACCEPT_CONTRACT="Yes"; yangcore sqlite:///:memory:

2.5.3.1 Listening Ports

A freshly installed version will open a single port by default.

This port uses the following parameters:

• local address: 127.0.0.1
• local port: 8080

These values may be changed using environment variables:

• The default local address may be changed using the “YANGCORE_INIT_ADDR” environment variable.
• The default local port may be changed using the “YANGCORE_INIT_PORT” environment variable.

For instance:

[Note: '\' line endings per RFC 8792]

$ export YANGCORE_INIT_ADDR="A.B.C.D"; \
  export YANGCORE_INIT_PORT="9090"; \
  yangcore sqlite:///:memory:

The default port presents the HTTP (without TLS) protocol over which the RESTCONF API is presented. A YANGcore-client must use this port to provide an initial configuration, including configuring YANGcore to open other listening ports and/or use TLS.

2.5.3.2 User Account

The default server (i.e., one that has never been configured) does not have any user accounts defined. A “user” here regards YANGcore’s northbound interface.

Prior to configuring a user, no client authentication needs to be supplied. It’s not possible, as none exists.

However, the very first configuration write request to a freshly installed YANGcore instance must configure at least one user account having unrestricted access to the system.

Additional users may be added/removed over time, but the software will ensure that there is at least one user having unrestricted access.

3.1.1.1 Using a MySQL Instance Installed on the Same Machine

Assuming a freshly installed MySQL instance running on the same machine as YANGcore, with an admin account called “root” with no password set, the following commands might be used to initialize a user account for YANGcore:

$ mysql -u root -e "CREATE USER 'testuser'@'localhost' IDENTIFIED BY 'secret';"
$ mysql -u root -e "GRANT ALL ON yangcore.* TO 'testuser'@'localhost';"
$ mysql -u root -e "FLUSH PRIVILEGES;"

Note: the grant above is to the yet-to-be-created “yangcore” database.

At which point YANGcore can be run as follows:

$ yangcore mysql+pymysql://testuser:secret@localhost:3306/yangcore

Note that YANGcore will itself create a database called “yangcore”¹⁰ and initialize all the tables in it¹¹.

The following command returns the database to the state before YANGcore ran:

$ mysql -u root -e "DROP DATABASE yangcore;"

And this command returns the database to the state before creating the user:

mysql -u root -e "DROP USER 'testuser'@'localhost';"

Note that, in all of the commands above, the string “localhost” could have been replaced with the string “127.0.0.1”. However, doing so switches from using a UNIX socket file to the TCP/IP stack. This may require setting the “bind-address” variable (e.g., in the “my.cnf” file) to “127.0.0.1” and restarting the MySQL server (i.e., ‘mysql.server restart’).

3.1.1.2 Using a MySQL Instance Installed on Another Machine

Assuming the MySQL instance is installed on another machine, the commands replace “localhost” with the appropriate IP addresses for the two machines.

For instance, assuming YANGcore is running on “1.1.1.1” and the MySQL instance is running on “2.2.2.2”, the MySQL user-creation commands would be:

$ mysql -u root -e "CREATE USER 'testuser'@'1.1.1.1' IDENTIFIED BY 'secret';"
$ mysql -u root -e "GRANT ALL ON yangcore.* TO 'testuser'@'1.1.1.1';"
$ mysql -u root -e "FLUSH PRIVILEGES;"

And for YANGcore to connect to it, the command would be:

$ yangcore mysql+pymysql://testuser:secret@2.2.2.2:3306/yangcore

Note that, in order for the MySQL server to support accepting connections from remote systems, its “bind-address” variable (e.g., in the “my.cnf” file) must either be unset, or set to either a specific IP address (i.e., “2.2.2.2”) or the wildcard address appropriate for the IP stack (e.g., “0.0.0.0” for IPv4). Be sure to restart the MySQL server afterwards (i.e., ‘mysql.server restart’).

3.1.2.1 Configure MySQL to Present the TLS Certificate

While it is possible to configure MySQL dyanmically, editing its configuration file (e.g., in the “my.cnf” file) is more understandable. Building on top of the previous example to bind the local address as well, the following is set:

[mysqld]
bind-address = 2.2.2.2

ssl_ca=mysqld-intermediate-cacerts.pem
ssl_cert=mysql-ee.pem
ssl_key=mysql-ee.key

require_secure_transport=ON

Be sure to restart the MySQL server afterwards (i.e., ‘mysql.server restart’).

3.1.2.2 Configure YANGcore to Authenticate the MySQL Server’s TLS Certifcate

YANGcore is “configured” to authenticate the server’s TLS certificate solely on the command line¹². Specifically:

$ yangcore --cacert mysqld-trust-anchor-certs.pem mysql+pymysql://testuser:secret@2.2.2.2:3306/yangcore

3.1.3.1 Configure MySQL to Authenicate TLS Clients

Building on top of the previous example, the “my.cnf” file is updated to:

[mysqld]
bind-address = 2.2.2.2

ssl_ca=mysqld-all-cacerts.pem
ssl_cert=mysql-ee.pem
ssl_key=mysql-ee.key

require_secure_transport=ON

Be sure to restart the MySQL server afterwards (i.e., ‘mysql.server restart’).

It is additionally necessary to change the “user” definition from before.

$ mysql -u root -e "CREATE USER 'testuser'@'1.1.1.1' REQUIRE X509;"
$ mysql -u root -e "GRANT ALL ON yangcore.* TO 'testuser'@'1.1.1.1';"
$ mysql -u root -e "FLUSH PRIVILEGES;"

Note that additional “REQUIRE” options exist to ensure that the client certificate contains a specific ‘SUBJECT’ and/or is signed by a specific ‘ISSUER’. These tests are in addition to the MySQL server testing that the client certificate has a chain of trust to any of the CA certificates contained in the file specified by the “ssl_ca” variable.

It is also possible to create a user that requires both a client certificate and a password:

$ mysql -u root -e "CREATE USER 'testuser'@'1.1.1.1' IDENTIFIED BY 'secret' REQUIRE X509;"
$ mysql -u root -e "GRANT ALL ON yangcore.* TO 'testuser'@'1.1.1.1';"
$ mysql -u root -e "FLUSH PRIVILEGES;"

3.1.3.2 Configure YANGcore to Send a Client Certificate to MySQL

YANGcore is “configured” to send a client certificate solely on the command line¹³. Specifically:

# NOTE: '\' line wrapping per RFC 8792

$ yangcore --cacert mysqld-trust-anchor-certs.pem --cert=yangcore-ee.pem \
        --key=yangcore-ee.key mysql+pymysql://testuser@2.2.2.2:3306/yangcore

Or, if also needing to pass a password:

# NOTE: '\' line wrapping per RFC 8792

$ yangcore --cacert mysqld-trust-anchor-certs.pem --cert=yangcore-ee.pem \
        --key=yangcore-ee.key mysql+pymysql://testuser:secret@2.2.2.2:3306/yangcore