10Configure mdm server and mdm CA server
In order to operate properly, the mdm server requires an XML preferences file as a configuration file, which can be specified during server start-up (see “Start and stop mdm server / mdm client” on page 43).
A default configuration file (preferences.xml) is contained in the mdm-server-1.12.x.zip file. Please unpack the ZIP file to get access to the preferences.xml file.
|
There are several passwords to be configured in the preferences.xml file. The respective keys accept the ENV:VARNAME pattern as value to take the password from the environment variable with name VARNAME. If you decide to use this pattern, please make sure that the respective environment variables are initialized before starting the server. |
10.1mdm server (preferences.xml file)
Node com
Default setting (do not change!)
node innominate
Default setting (do not change!)
node innomms
Default setting (do not change!)
node is
Key expertMode
If set to true, some unsupported configuration variables which are normally hidden are made available in the Device and Template properties dialog (default: false). Additionally, the mGuards are configured such that unsupported configuration variables become visible in their web interfaces. Please do not change this value!
Key defaultAdminPassword
The password of the admin user on newly created mGuards (default: mGuard). The default value corresponds to the mGuard factory default. If mGuard devices are pre-configured before they are used with mdm, a different default admin password can be set and the database must be updated by the following command:
java -Xmx1024m -jar mdm-server-1.12.x.jar update preferences.xml
Key defaultRootPassword
The password of the root user on newly created mGuards (default: root). The default value corresponds to the mGuard factory default. If mGuard devices are pre-configured before they are used with mdm, a different default root password can be set and the database must be updated by the following command:
java -Xmx1024m -jar mdm-server-1.12.x.jar update preferences.xml
Key overrideDefaultPasswordNt
If set to "True", FL MGUARD 1000 devices will use as default password the admin password specified in key defaultAdminPassword. The default is "False".
Node license
Key licenseFile
Name and path of the license file.
Node device
Node licenseServer
–Key proto
The protocol to be used to access the license server (default: http). Please do not change this value.
–Key address
The address of the license server (default: online.license.innominate.com). Please do not change this value.
–Key port
The port to be used to access the license server (default: 80). Please do not change this value.
–Key reqPage
The CGI script to be called when requesting licenses (default: cgi-bin/autoreq.cgi). Please do not change this value.
–Key refPage
The CGI script to be called when refreshing licenses (default: cgi-bin/autorefresh.cgi). Please do not change this value.
–Key reqProfKey
The CGI script to be called when requesting profile keys (default: cgi-bin/autodevcert.cgi). Please do not change this value.
–Key reqUsername
The user name needed to request profile keys. Please contact Phoenix Contact support to obtain a user name.
–Key reqPassword
The password needed to request profile keys. Please contact Phoenix Contact support to obtain a user name.
–Key retries
The number of retries to contact the license server (default: 3). Please do not change this value.
–Key timeout
The timeout in seconds when contacting the license server (default: 60). Please do not change this value.
Node connection
–Key useProxy
Here you can configure whether a proxy should be used to contact the license server (default: false).
–Key proxyAddress
The address of the proxy to contact the license server (default: 127.0.0.1).
–Key proxyPort
The port of the proxy to be used to access the license server (default: 3128).
–Key proxyRequiresAuthentication
Boolean defining whether the proxy requires authentication (default: false).
–Key proxyAuthenticationUsername
Key proxyAuthenticationPassword
Key proxyAuthenticationRealm
The credentials to be used if the proxy requires authentication (default: empty).
Node service
Key address
The IP address designating the network interface on which the server is listening for client connections. If you specify 0.0.0.0, the server is listening on all interfaces (default: 127.0.0.1).
Key port
The port number on which the server is listening for client connections (default: 7001).
Key backlog
Number of log entries to be stored (default: 50).
Key storage
The storage to be used (default: database).
Node security
Key keyStore
Name and path of the keystore file.
Key keyStoreType
Format of the keystore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
Key keyStorePassword
Password for the keystore file. The special value ENV:PASSWORD_SSL will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_SSL; the name PASSWORD_SSL is just an example and can be changed if desired.
Key trustStore
Name and path of the truststore file.
Key trustStoreType
Format of the truststore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
Key trustStorePassword
Password for the truststore file. The special value ENV:PASSWORD_SSL will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_SSL; the name PASSWORD_SSL is just an example and can be changed if desired.
Node session
Key maxInactiveInterval
The maximum time interval of inactivity (in seconds) that the server will keep a session open between client accesses.
A negative or zero time (default) indicates a session should never time out.
Key maxConcurrentSessions
The maximum number of concurrent sessions (= connected clients). A negative or zero count (default) indicates that the upper limit of the number of concurrent sessions is defined by the license.
Node storage
–Node database
–Key host
The IP address (or hostname) mdm should connect to to get access to the PostgreSQL database (default: 127.0.0.1).
–Key port
The port that mdm should use to connect to the database (default: 5432).
–Key name
The name of the database (default: innomms).
–Key user
The user of the database (default: innomms).
–Key password
The password to be used to connect to the database (default: ENV:PASSWORD_DB).The special value ENV:PASSWORD_DB will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_DB; the name PASSWORD_DB is just an example and can be changed if desired.
–Key ssl
Enable/disable secure connection between the mdm server and the PostgreSQL server. Please note that enabling this option requires additional installation steps (default: false).
–Node update
–Node scheduler
Key tries
Maximum number of attempts for an upload or export of a device configuration. If this maximum is reached, mdm will stop trying to upload a configuation to the device (default: 5).
Key timeout
Maximum number of seconds until an upload of the device configuration is cancelled. After the timeout is reached, mdm will stop trying to upload a configuation to the device (default: 600).
Key rescheduleDelay
Number of seconds between upload attempts (default: 45).
–Node firmwareUpgradeScheduler
Key tries
Maximum number of connections mdm should attempt to get feedback from the device on the result of the firmware upgrade. If this maximum is reached, mdm will stop trying to contact the device (default: 5).
Key timeout
Maximum number of seconds until mdm stops to contact a device for the result of a firmware upgrade. After the timeout is reached, mdm will indicate that the firmware upgrade failed (default: 3600).
Key rescheduleDelay
Intervall in seconds between two attempts to obtain the result of a firmware upgrade from the device (default: 300).
–Node ssh
Key connectTimeout
Timeout for the initial SSH connect to a device (default: 60).
Key socketTimeout
Timeout for the SSH connection TCP/IP socket, e.g. lost connection (default: 120).
This timeout will get activated, if a device did not answer a command started on the device (default: 120).
–Node pull
Node export
Key directory
The export base directory on the server where the configuration files should be exported to (e.g. for the configuration pull). Please note that the configuration files are always exported by the server and not the client, i.e. the client does not have any access to the files. The specified directory pathname should have the appropriate format of the respective OS (default: the default temporary directory of your installation, e.g. /tmp for Linux).
Key filenames
A comma-separated list of naming schemes for pull configuration exports.
dbid: A unique ID (automatically assigned) is used as filename and the files are written to the export base directory.
serial: The serial number is used as filename and the files are written to the serial/ subdirectory of the export base directory.
mgntid: The Management ID is used as filename and the files are written to the mgntid/ subdirectory of the export base directory (default: dbid,serial,mgntid).
Node feedback
Key port
The mGuards can pull their configurations from an HTTPS server. Since the HTTPS server is a separate application, mdm does not get any direct feedback about the result of a configuration pull. To enable the feedback mechanism, mdm has to be configured as a Syslog server in the HTTPS server settings. mdm will then receive and analyze the HTTPS server syslog messages and display the result of configuration pulls in the client.
It is recommend to use an unprivileged port (above 1024) so that the server can be run without administrator/root privileges (default: 7514).
–Node nt
This node contains the configuration information necessary for interaction with FL MGUARD 1000 devices.
Node python
Key path
The path leading to the Python 3.8 installed on the system. Under Linux this is typically just "python" or e.g. "python3.8" if a different Python version is to be used.
Node tools
Key initConverter
Creates the file "download_info.json" if it is not available in the system. The path to the file "create_download_info.py" must be specified here.
Key downloadInfo
Contains the relevant information for a successful GET request to the FL MGUARD 1000 device via REST client. The path to the file "download_info.json" must be specified here.
Key atv2json
Path to the Python script "atv2json.py“. The script is used by mdm to convert ATV profiles of the firmware "mGuard NT x.y" into JSON objects compatible with FL MGUARD 1000 devices.
Key json2atv
Path to the Python script "json2atv.py“. The script is used by mdm to convert JSON objects exported from FL MGUARD 1000 devices to ATV profiles compatible with the "mGuard NT x.y" firmware.
Key mgclient
Path to the Python script "main.py". The script is used to upload JSON configuration objects corresponding to devices with "mGuard NT x.y" firmware to FL MGUARD 1000 devices. The script is also used to import the current configuration from the FL MGUARD 1000 device into mdm using a GET request.
Node auth
Node radius
–Key numServers
Set this to the number of RADIUS servers to enable RADIUS authentication. Please refer to “User authentication” on page 142 for more detailed information. If set to 0, RADIUS authentication is disabled (default: 0).
–Key timeout
The number of seconds that the mdm server waits for a reply from a RADIUS server. Only used if RADIUS authentication is enabled (default: 5).
–Key retries
The number of times that the mdm server sends requests to the RADIUS servers. If no reply is received within timeout seconds for retries times, the authentication request is considered failed. Only used if RADIUS authentication is enabled (default: 3).
–Key nasIdentifier
The NAS Identifier included in RADIUS requests sent by the mdm server. Some RADIUS servers ignore this, in which case the default value can be left unchanged (default: nas.identifier.example).
Nodes 0, 1, … (up to the number of RADIUS servers minus one)
Each numbered node identifies a single RADIUS server.
–Key host
The hostname or IP address of the RADIUS server (default: localhost).
–Key port
The port on which the RADIUS server listens for incoming requests (default: 1812).
–Key sharedSecret
The shared secret used to authenticate the RADIUS request. The same shared secret must be configured in the RADIUS server (default: secret).
Node locale
Country and language specific settings.
Leave the defaults, since these settings are not fully supported yet!
Key language
Key country
Key variant
Node logging
Node syslog
–Key numReceivers
Set this to the number of syslog receivers to which mdm sends log messages. If set to 0, logging via syslog is disabled (default: 1).
–Key logLevel
The minimum severity of the messages to log via syslog. Messages with a severity lower than the specified one are suppressed (default: INFO).
The following severities can be used:
–SEVERE (highest severity)
–WARNING
–INFO
–CONFIG
–FINE
–FINER
–FINEST (lowest severity)
–Nodes 0, 1, … (up to the number of syslog servers minus one)
Each numbered node identifies a single syslog server.
–Key host
The hostname or IP address of the syslog server (default: localhost).
–Key port
The port on which the syslog server listens for incoming log messages (default: 514).
Node configurationHistory
Key expireAfterDays
Configuration history entries older than the specified number of days are automatically expired (i.e. removed from the history).
If the value 0 is used, configuration history entries are never expired (default: 14).
The maximum value is 365250 (1000 years). If the value is < 0 or > 365250 or not an integer, the default value of 14 is assumed.
Please refer to “Configuration history” on page 153 for more detailed information on configuration history entries.
Node event
Key cleanupDays
Persistent event log entries older than the specified number of days are automatically expired (i.e. removed from the event log).
If the value 0 is used, Persistent event log entries are never expired (default: 200).
The maximum value is 365250 (1000 years). If the value is < 0 or > 365250 or not an integer, the default value of 200 is assumed.
Please refer to “Persistent Event Log” on page 53 for more detailed information on persistent event log entries.
Node CA
These settings are required only if a CA is used.
Key type
The type of CA to use. Valid values are mdm-CA to use the mdm CA or SCEP to communicate with a CA via SCEP (default: mdm-CA). Please refer to “Machine certificates” on page 143 for more detailed information on SCEP.
Key protocol
The protocol to be used to connect to the mdm CA. Valid values are http or https (default: https). When using the mdm CA, only https should be used since the mdm CA relies on transport layer security for authentication purposes. SCEP includes application layer authentication mechanisms, so http is usually used with SCEP.
Key host
The hostname or IP address of the CA server (default: localhost).
Key port
The port on which the CA server listens for incoming requests (default: 7070). If 0 is specified, the https or http default port is used.
Key requestDirectory
The path within the URL the mdm server uses for certification requests (default: request). When using the mdm CA, request must be used. When using SCEP, consult the documentation of the CA server. If e.g. the Microsoft Windows Server 2008 CA is used, CertSrv/mscep/mscep.dll should be specified.
Key revocationDirectory
The path within the URL the mdm server uses for certificate revocation requests (default: revoke). When using the mdm CA, revoke must be used. Not applicable when SCEP is used.
Key rsaKeySize
The size (in bits) of the RSA modulus the mdm server uses to generate RSA key pairs (default: 2048).
Node SCEP
–Key name
The instance name used in SCEP requests (default: mdm). Please note that some CAs ignore the instance name, but still require a non-empty value.
Node httpServer
These settings are required only, if the mdm server should be started as a RESTful server.
Key start
RESTful services of the mdm server can be enabled (value: true) or disabled (value: false). Default value: false.
Key address
The hostname or IP address on which the mdm RESTful server listens for incoming requests (default: 127.0.0.1).
If you specify 0.0.0.0, the mdm RESTful server listens on all interfaces.
Key port
The port on which the mdm RESTful server listens for incoming requests (default: 7080).
10.2mdm Certification Authority (CA)
mdm provides its own Certification Authority (CA). The mdm CA is a separate server instance. The CA is used to issue machine certificates for the mGuards, e.g. if you would like to use X.509 authentication for your VPN tunnels. Please refer to “Configure VPN connections” on page 127 and “Manage X.509 certificates” on page 143 on how to request certificates for an mGuard using the CA.
If you are not going to configure VPN tunnels with mdm or if you would like to use your own CA or pre-shared keys (PSK), the installation of the mdm-CA is not required.
The purpose of the mdm CA is to issue certificates, which are requested by the mdm server to be used as machine certificates for mGuards.
The mdm CA is implemented as a stand alone server. Its interface to the mdm server is a servlet driven web server (HTTP), which can be secured with SSL (HTTPS) and which can enforce client authentication. Especially in production environments Phoenix Contact highly recommends to use HTTPS with client authentication, because only then is it assured that the mdm CA will issue certificates to authenticated clients only.
The configuration file of the mdm CA server allows to configure different keystores (isolation) for the generation of certificates (CA-keystore) and for the SSL authentication (SSL-keystore, SSL-truststore). This assures that the CA private key (intended for issuing machine certificates) is not accidentally used for SSL authentication.
The mdm CA stores all required information in a PostgreSQL database. The communication between the mdm CA and the database should be also secured using SSL.
All the required keys and certificates to secure the communication between mdm CA, mdm server and the database have to be generated, installed in the file system and configured in the ca-preferences.xml file of the CA component and also in the preferences.xml file of the mdm server.
There are many tools to create and manage keys and certificates. This document describes the usage of the OpenSSL tools, which are available for Linux and Windows (e.g. as stand-alone binary or as part of the cygwin package). The tools to create the certificates, keys, and keystores need not be installed on the mdm CA target system.
10.2.2mdm CA server (ca-preferences.xml file)
This chapter describes the content of the configuration file ca-preferences.xml. Please adapt ca-preferences.xml according to your environment if necessary.
Node certificateFactory
Key validityPeriodDays
Number of days certificates issued by the mdm CA shall be valid (i.e. each certificate will be valid for the specified number of days starting from the time of its issuance).
Key certTemplate
Name and path of a certificate file to be used as template for new VPN certificates issued by the mdm CA.
Key keyStore
Name and path of the keystore file (see Chapter 10.2).
Key keyStoreType
Format of the keystore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
Key keyStorePassword
Password for the keystore file (see Chapter 10.2). The special value ENV:PASSWORD_CA will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_CA; the name PASSWORD_CA is just an example and can be changed if desired.
Key keyAlias
Name of the entry within the keystore, where the private key and associated public key certificate can be found (the keystore may contain more than one entry) - default matches the one from the example scripts described in Chapter 10.2.2. To find out the alias names in a .p12 file please use the command:
openssl pkcs12 -in <filename>.p12 -nodes
The alias is shown as Friendly Name in the output.
To find out the alias names in a JKS file please use the command:
keytool -list <filename>
Key keyPassword
Password to decrypt the RSA private key contained within the keystore (see entry keyAlias); the special value ENV:PASSWORD_CA will cause the mdm CA server to read this password upon startup from the environment variable named PASSWORD_CA; the name PASSWORD_CA is just an example and can be changed if desired.
Key crlExportDirectory
The path to the directory that is used by the mdm CA to export the files containing the CRLs (Certificate Revocation Lists). Each file contains a PEM encoded X.509 CRL of revoked certificates from a single issuer. The filename of each CRL file is composed of the hash value of the issuer with a crl extension, e.g. 5E84D566026616ED32169580A913661499FA6B03.crl. Please make sure that the files contained in this directory are accessible from the mGuards. To configure the CRL URL on the mGuards please navigate to Authentication » Certificates » CRLs in the Device or Template properties dialog (mGuard 5.0 or later only) and add the correct URL to the CRL table. Please refer to Chapter 7.4.1 for more details on certificate revocation (default: security/crl).
Key crlUpdatePeriodMinutes
The time interval in minutes how often CRLs are exported to the crlExportDirectory. When a certificate is revoked, a CRL is exported immediately. Additionally, CRLs are exported periodically according to the specified time interval.
Key nextUpdatePeriodDays
The number of days into the future written into the Next Update field in exported CRLs. The field is a hint for the mGuard downloading the CRL when it is to be considered obsolete. It should therefore be significantly larger than crlUpdatePeriodMinutes (but note that crlUpdatePeriodMinutes is specified in minutes, while nextUpdatePeriodDays is specified in days).
Node storage
–Node database
–Key host
The IP address (or hostname) the mdm CA should connect to to get access to the PostgreSQL database (default: 127.0.0.1).
–Key port
The port that the mdm CA should use to connect to the database (default: 5432).
–Key name
The name of the database (default: mdmca).
–Key user
The user of the database (default: mdmca).
–Key password
The password to be used to connect to the database; the default value ENV:PASSWORD_DB will cause the mdm CA server to read this password upon startup from the environment variable named PASSWORD_DB; the name PASSWORD_DB is just an example and can be changed if desired.
–Key ssl
Enable/disable secure connection between the mdm CA and the PostgreSQL server. Use the value true to enable secure connections.
–Key loglevel
Internal use only. Please do not change (default: 0).
–Node security
Key trustStore
Name and path of the truststore file containing the trusted certificate of the database server.
Key trustStoreType
Format of the truststore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
Key trustStorePassword
Password for the truststore file (see Chapter 10.2). The special value ENV:PASSWORD_SSL will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_SSL; the name PASSWORD_SSL is just an example and can be changed if desired.
Node certificationRequestHandler
Key maxRequestLength
Number of bytes PKCS#10 certification requests can have at most; longer requests will be rejected to defend against simple DoS attacks (default: 102400).
Node revocationRequestHandler
Key maxRequestLength
Number of bytes revocation requests must have at most; longer requests will be rejected to defend against simple DoS attacks (default: 10240).
Node httpServer
Key host
IP address or hostname of the interface to listen on with the mdm CA's servlet interface; value 0.0.0.0 means to listen on any interface (default: 127.0.0.1).
Key port
Port number the server should listen on for incoming connections (default: 7070).
Key minThreads
Minimum number of instantiated HTTP server threads the mdm CA shall maintain in its pool (default: 2).
Key lowThreads
Internal use only. Please do not change.
Key maxThreads
Maximum number of instantiated HTTP server threads the mdm CA shall keep in its pool (default: 5).
Key protocol
The protocol the mdm CA's servlet interface should use; either http or https. To enable secure communication, https should be used.
Node https
The configuration in this node is used only if protocol in node httpServer is https.
–Key keyStore
Name and path of the keystore file.
–Key keyStoreType
Format of the keystore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
–Key keyStorePassword
Password for the keystore file. The special value ENV:PASSWORD_SSL will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_SSL; the name PASSWORD_SSL is just an example and can be changed if desired.
–Key keyPassword
The password required to decrypt the SSL private key contained in the keystore for the HTTPS server.
–Key clientAuth
Boolean value; true means clients need to authenticate via SSL too (not just the server); false means clients do not need to authenticate. This value should be set to true.
–Key trustStore
Name and path of the truststore file containing the trusted certificates for the SSL connection from the clients.
–Key trustStoreType
Format of the truststore, either JKS (Java KeyStore) or PKCS12 (OpenSSL).
–Key trustStorePassword
Password for the truststore file (see Chapter 10.2). The special value ENV:PASSWORD_SSL will cause the mdm server to read this password upon startup from the environment variable named PASSWORD_SSL; the name PASSWORD_SSL is just an example and can be changed if desired.
Node logging
Key file
The base name of the rotated log file the mdm CA will produce; the file name may be used with a relative or absolute path name. The suffix n.log will be appended to the base name, with n being a non-negative integer.
Key limit
Maximum number of bytes a log file of the mdm CA can reach; when it grows beyond this number, it will be rotated.
Key count
Maximum number of rotated log files the mdm CA should keep.
Key level
Defines granularity of the logging messages the mdm CA will produce; acceptable values are:
–OFF
–SEVERE (highest value)
–WARNING
–INFO
–CONFIG
–FINE
–FINER
–FINEST (lowest value)
–ALL
