Migration to Standalone
This chapter provides a guideline for migrating a nevisIDM instance with container type adnjboss (v5.1.x) or adnwildfly (v10.1.x) to a nevisIDM instance of deployment type "standalone".
There is no automated instance migration. Gather the information from the current source instance and use it to create a new target standalone instance. This document covers the most common configuration use cases and makes recommendations for their migration.
Instance parameters gathering
Server parameters
In a first step, gather all the required parameters of the current instance. See also the following table. Some parameters are only required if TLS is used.
If all the required parameters are known, you can skip the step Parameter retrieval.
| Parameter | Default | Description |
|---|---|---|
| SERVER_URL_PROTOCOL | http or https | The server protocol. In case of TLS the protocol is https. |
| SERVER_URL_SERVER | localhost | The server host name. |
| SERVER_URL_PORT | 8989 | The server port. |
| SERVER_TLS_KEYSTORE | /var/opt/neviskeybox/ default/default/node_keystore.jks | Keystore used to identify the server (sent to the client on a SSL/TLS client hello).(info) Only required for TLS. |
| SERVER_TLS_KEYSTORE_PASSWORD | Passphrase to access the server keystore.(info) Only required for TLS. | |
| SERVER_TLS_TRUSTSTORE | /var/opt/neviskeybox/ default/default/truststore.jks | Truststore used to validate client certificates.(info) Only required for TLS. |
| SERVER_TLS_TRUSTSTORE_PASSWORD | Passphrase to access the server truststore (usually not required, because the truststore contains public certificates, which do not require protection).(info) Only required for TLS. | |
| NINJA_CERT | /var/opt/neviskeybox/ default/nevis/truststore.jks | This parameter is used to configure the trust anchor for Nevis SecToken validation. It is used by the Nevis JAAS login module. |
Parameter retrieval
adnjboss
The required parameters can be retrieved as described in chapter Parameter retrieval of the Migration Guide from adnjboss to adnwildfly.
adnwildfly
The server parameters can be retrieved from security realms, security domains, interfaces and socket bindings configured in the file standalone.xml. You can access this file either with the command nevisidm <instance_name> config server, or by opening the file /var/opt/adnwildfly/instances/<new_instance_name>/standalone/configuration/standalone.xml.
The following two examples show the standalone.xml file for the protocol types HTTPS and HTTP, respectively.
HTTPS standalone.xml
<security-realms>
<security-realm name="SslRealm">
<server-identities>
<ssl>
<keystore path="${SERVER_TLS_KEYSTORE}" keystore-password="${SERVER_TLS_KEYSTORE_PASSWORD}"/>
</ssl>
</server-identities>
<authentication>
<truststore path="${SERVER_TLS_TRUSTSTORE}" keystore-password="${SERVER_TLS_TRUSTSTORE_PASSWORD}"/>
</authentication>
</security-realm>
</security-realms>
<profile>
<subsystem xmlns="urn:jboss:domain:undertow:1.2">
<buffer-cache name="default" />
<server name="default-server">
`<http-listener name="default-ssl" socket-binding="https" security-realm="SslRealm"/>
<host name="default-host" alias="${SERVER_URL_SERVER}"/>
</server>
<servlet-container name="default">
<jsp-config />
</servlet-container>
</subsystem>
<subsystem xmlns="urn:jboss:domain:security:1.2">
<security-domains>
<security-domain name="NevisSecTokenDomain" cache-type="default">
<authentication>
<login-module code="ch.nevis.ninja.jboss.auth.NinjaJbossLoginModuleImpl" flag="required" module="ch.nevis.ninja">
<module-option name="NevisSignerCertificate" value="${NINJA_CERT}"/>
<module-option name="UserGetter" value="AttributeUserGetter(source=loginId)"/>
<module-option name="AdjustIdentity" value="true"/>
<module-option name="LogDebug" value="false"/>
<module-option name="RoleGetters" value="ch.nevis.ninja.commons.mapping.StaticRoleGetter, ch.nevis.ninja.commons.mapping.TokenRoleGetter"/>
</login-module>
</authentication>
</security-domain>
</security-domains>
</subsystem>
</profile>
<interfaces>
<interface name="public">
<inet-address value="${SERVER_URL_SERVER}"/>
</interface>
</interfaces>
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
<socket-binding name="https" port="${SERVER_PORT}" fixed-port="true" />
</socket-binding-group>
HTTP standalone.xml
<profile>
<subsystem xmlns="urn:jboss:domain:undertow:1.2">
<buffer-cache name="default"/>
<server name="default-server">
<http-listener name="default" socket-binding="http" redirect-socket="http"/>
<host name="default-host" alias="${SERVER_URL_SERVER}"/>
</server>
<servlet-container name="default">
<jsp-config/>
</servlet-container>
</subsystem>
<subsystem xmlns="urn:jboss:domain:security:1.2">
<security-domains>
<security-domain name="NevisSecTokenDomain" cache-type="default">
<authentication>
<login-module code="ch.nevis.ninja.jboss.auth.NinjaJbossLoginModuleImpl" flag="required" module="ch.nevis.ninja">
<module-option name="NevisSignerCertificate" value="${NINJA_CERT}"/>
<module-option name="UserGetter" value="AttributeUserGetter(source=loginId)"/>
<module-option name="AdjustIdentity" value="true"/>
<module-option name="LogDebug" value="false"/>
<module-option name="RoleGetters" value="ch.nevis.ninja.commons.mapping.StaticRoleGetter, ch.nevis.ninja.commons.mapping.TokenRoleGetter"/>
</login-module>
</authentication>
</security-domain>
</security-domains>
</subsystem>
</profile>
<interfaces>
<interface name="public">
<inet-address value="${SERVER_URL_SERVER}"/>
</interface>
</interfaces>
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
<socket-binding name="http" port="${SERVER_PORT}" fixed-port="true"/>
</socket-binding-group>
Old instance stopping
Once you have gathered the required parameters, you can stop the old instance.
Use the following command:
nevisidm <instance_name> stop
Upgrade nevisIDM
The latest version of nevisIDM has deprecated the support of adnjboss. Therefore, if your old nevisIDM instance is of deployment type adnjboss, make sure to stop itbefore you upgrade nevisIDM to the latest version.
The next step is to install the latest version of nevisIDM (at least 2.72.0.x) on the server.
Standalone instance creation
The deployment type standalone is the default. To create a new standalone instance, use the following command:
Standalone instance creation
nevisidm inst create <new_instance_name>
Instance configuration migration
Copy configurations
The following configuration files can be copied from the adnjboss/adnwildfly instance directly to the standalone instance:
cp -f /var/opt/nevisidm/<instance_name>/conf/attrAccess.properties /var/opt/nevisidm/<new_instance_name>/conf/attrAccess.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/authorizationConfig.properties /var/opt/nevisidm/<new_instance_name>/conf/authorizationConfig.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/batchjobContext.xml /var/opt/nevisidm/<new_instance_name>/conf/batchjobContext.xml
cp -f /var/opt/nevisidm/<instance_name>/conf/batchjob-config-reloader.properties /var/opt/nevisidm/<new_instance_name>/conf/batchjob-config-reloader.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/rolesAssignment.properties /var/opt/nevisidm/<new_instance_name>/conf/rolesAssignment.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/rolesMapping.properties /var/opt/nevisidm/<new_instance_name>/conf/rolesMapping.properties
cp -f /var/opt/nevisidm/<instance_name>/conf/tlds-alpha-by-domain.txt /var/opt/nevisidm/<new_instance_name>/conf/tlds-alpha-by-domain.txt
Migrate configurations
Manually migrate the following files of the adnjboss/adnwildfly instance (see below). Each custom configuration that differs from the default value will be adjusted or set in the corresponding newly generated files of the standalone instance. It is recommended that you use a diff tool like Meld to compare the two versions.
nevisidm-prod.properties
Besides migrating each custom configuration, also add the server parameters retrieved in the step Parameter retrieval to the newly generated nevisidm-prod.properties file:
server.tls.enabled=<false for HTTP, true for HTTPS>
server.tls.require-client-auth=<false for one-way TLS, true for two-way TLS>
server.host=<SERVER_URL_SERVER>
server.port=<SERVER_URL_PORT>
server.tls.keystore=<SERVER_TLS_KEYSTORE>
server.tls.keystore-passphrase=<SERVER_TLS_KEYSTORE_PASSWORD>
server.tls.truststore=<SERVER_TLS_TRUSTSTORE>
server.tls.truststore-passphrase=<SERVER_TLS_TRUSTSTORE_PASSWORD>
server.auth.ninja.truststore=<NINJA_CERT>
log4j.xml
Do not simply overwrite the new log4j.xml file by the old configuration file, because new categories for the standalone logging have been added. Migrate every custom configuration, i.e., categories, to the newly generatedlog4j.xml file.
Custom facing
See the following page for more information about custom facing migration.
vmargs.conf
There is no vmargs.conf file for the standalone deployment type. JVM arguments can be configured by setting the JAVA_OPTS environment variable in the file env.conf.
Migrate and append each custom configuration in the vmargs.conf file to the JAVA_OPTS environment variable in the env.conf file.
Special configurations
Login modules
No additional login module configuration is required for client certificate or secToken authentication in the standalone deployment.
In standalone deployment, the login modules for both client certificate and SecToken authentication are enabled per default. The two login modules are chained, that is, at least a valid client certificate or a valid SecToken as authentication information is required for a successful login. In case a request contains both a client certificate and a SecToken, the SecToken will be used for the login.
Client certificate authentication
In the standalone deployment, you can use the same server port as before for client certificate authentication. In addition, the ForwardSerlvet does not have to be configured as JVM argument anymore.
JMS
The standalone deployment has a built-in JMS queue. The port, storage location, username and password can be configured via the nevisidm-prod properties. For further information, see JMS parameters.
OpenJDK migration
The standalone deployment requires Java OpenJDK. For migration information, see Migrating to OpenJDK 1.8.0.
Standalone instance start
When the migration is completed, you can start the new standalone instance. Use the following command:
nevisidm <new_instance_name> start
Old instance removal
When you have successfully completed the migration and started the new instance, you can remove the old instance. Use the following command:
nevisidm inst remove <instance_name>
The latest version of nevisIDM has deprecated the support of adnjboss. Therefore, if your old nevisIDM instance was of deployment type adnjboss, remove it manually.