How to Change the IP Address of YSoft SafeQ Management Server

This document describes how to change the IP address of one YSoft SafeQ Management Server that is a standalone server or a member of a cluster. These guidelines are typically used in the environment where YSoft SafeQ Management Server runs on the same server as other components (such as YSoft SafeQ Spooler Controller, YSoft SafeQ Payment System, ...).


Verification of the IP Address

This section describes the way to find the IP address of the current server.

  1. Log into the server where the IP address is changed.

  2. Open command prompt (e.g., Start => Run => cmd).

  3. Enter the ipconfig command in the command prompt and press Enter.

  4. Check IPv4 Address from the command output.


images/download/attachments/160480352/ipconfig.PNG

Reconfiguration of Management Server

An Environment with a Single Management Server

Enable license reactivation if you plan to move YSoft SafeQ Management Server to a different server with a new IP address.

This scenario assumes that you have a Backup of Databases and a Backing Up Configuration and Binary Files available.

  1. If you have only one standalone YSoft SafeQ Management Server, uninstall it.

  2. Prepare a server (or virtual machine) with the new IP address.

  3. If you are using an external database (on another server), check its state.

    1. If the external database is damaged, perform a Recovering Databases but skip the Finalization part for now.

  4. Check the backup of the configuration files and note the following:

    1. Which optional features were installed:

      1. Mobile Print Server – the MPS folder is available in the backup files.

      2. Payment System – the YPS folder is available in the backup files.

    2. A Management Server GUID. It is noted in the safeq.properties file as the value of the parameter communicator.cml.guid. For example:

      backup\Management\conf\safeq.properties
      # COMMUNICATOR
      communicator.cml.guid = MGMT1

    3. A SPOC GUID. It is noted in the guid.conf file as the value of the LocalGUID option. For example:

      backup\SPOC\conf\modules\guid.conf
      localGUID = ectp5o8ep0op3hzi

  5. Reinstall Management Server using the same build version of the installation package as you were using before.

    1. Enable optional features if they were used before (see step 4.a.)

    2. Provide the wizard with the same Management Server GUID that was used before (see step 4.b.)

    3. If you have YSoft SafeQ 6 MU11 or newer build:

      Provide the wizard also with the same SPOC GUID that was used before (see step 4.c.)

    4. Finish the installation.

      See First server installation for a detailed procedure.

  6. Stop almost all YSoft services after installation has finished.

    1. Leave only this YSoft service running:

      1. YSoft Bundled PostgresSQL 9.4 (available if embedded PostgresSQL DB is used)

    2. You can use the following PowerShell script to perform the task

      Get-Service *YSoft* | Where-Object {$_.Name -notmatch 'YSoftPGSQL'} | Stop-Service

  7. If you are using an embedded PostgreSQL database, perform a Recovering Databases but skip the Finalization part for now (as new empty databases were created during installation).

  8. Update the IP addresses in the database.

    1. Connect to the SQDB6 database, the cluster_mngmt schema, and check the contents of the cluster_server table:

      1. If there is only one record with the server_guid of the reinstalled node, then update the ip_address value to match the new node.

      2. If there are two records with the same server_guid but different ip_address, then delete the record that contains the IP address of the old server.

    2. Connect to the SQDB6 database, tenant_1 schema (or the schema to which your server with the replaced IP address belonged, tenant_1 is default), and check the contents of spooler_controllers table:

      1. Find the record where spooler_controller_guid equals the GUID of your replaced SPOC (see step 4.c), then update the network_address value to match the new IP.

  9. If you have YSoft SafeQ 6 MU10 or older build:Edit <instal_dir>\SPOC\conf\modules\guid.conf (e.g. c:\SafeQ6\SPOC\conf\modules\guid.conf) and rewrite the localGUID to the value that was used before (see step 4.c.).

  10. Delete the SPOC cache by deleting the whole folder <install_dir>\SPOC\SpoolCache

  11. Start YSoft services with an Automatic startup type again.

    Do not start the YSoft SafeQ Spooler Controller Group Service service. It will be started by the YSoft SafeQ Spooler Controller service when the proper configuration is ready.

    1. You can use the following PowerShell script to perform the task:

      Get-Service *YSoft* | Where-Object {$_.Name -ne 'YSoftSQ-SPOCGS'} | Start-Service

  12. Re-activate your YSoft SafeQ 6 license using your preferred method (online/offline). See Management Interface - License Activation for detailed instructions.

  13. If YSoft SafeQ Payment System is installed on this server, update paymentSystemApiUrl.

    • In YSoft SafeQ Print Management web, system update paymentSystemApiUrl to reflect the new IP address.

  14. Restore customized configuration:

    1. If you had services running under a specific domain account, set it up again.

    2. If you used customized scripts on the server (e.g., for batch files launched by Rule-Based Engine or customized batch files used by Workflow Processing System), restore those scripts from the backup.

    3. If you used a customized configuration (such as your own certificates for the web services), locate the relevant documentation and set the configuration again.

  15. Check that Spooler Controller is correctly connected on the management web.

An Environment with Two Management Servers in the Cluster

This procedure is valid only for installations where an external database located on another server is being used.

If the affected node is the one on which the YSoft SafeQ 6 license was activated, enable license reactivation before transferring the license to a new server.

  1. Make sure both existing servers (including the one that should be replaced by the other one with a new IP address) are functional.

  2. If you have two node cluster, add a third node that is using the new IP address.

  3. Then uninstall the node that is being replaced.

  4. Edit <install_dir>\SPOC\conf\modules\spoc.conf on both remaining Management Servers

    1. Make sure the details about and correct IPs for both remaining nodes are stored in the properties: serverGUID1, serverPORT1, serverIP1, serverGUID2, serverPORT2, serverIP2

    2. Should details about any node (except the one which is going to be removed) be missing, add them.

  5. Remove IP address of the uninstalled node from the database

    1. Connect to the SQDB6 database, cluster_mngmt schema and check the contents of the cluster_server table.

    2. Delete the record that contains ip_address and server_guid of the server that was uninstalled.

  6. Restart the YSoft SafeQ Management Service service on both Management Servers in the cluster.

  7. If the reinstalled node was the one on which the YSoft SafeQ 6 license was activated, re-activate YSoft SafeQ 6 license using your preferred method (online/offline). See Management Interface - License Activation for detailed instructions.

  8. If the reinstalled node also contained a SPOC:

    1. move the MFDs managed by the uninstalled SPOC to the SPOC with a new IP address (YSoft SafeQ management interface -> Devices).

    2. delete the uninstalled SPOC from YSoft SafeQ (YSoft SafeQ management interface -> Devices -> Spoler Controller groups).

    3. if the old SPOC was member of a SPOC group, move the newly installed server to a SPOC group (YSoft SafeQ management interface -> Devices -> Spooler Controller groups).

      • other necessary steps to fully initialize a SPOC group are described later in this guide.

An Environment with Three or More Management Servers in the Cluster

This procedure is valid only for installations where an external database located on another server is being used.

Stop YSoft SafeQ services

  1. Stop all YSoft SafeQ services on the affected server.

    1. You can use the following PowerShell script to perform the task

      Get-Service *YSoft* | Stop-Service

Update the IP address in the database

Replace the old IP address with the new one in the SQDB6 database, the cluster_mngmt schema, the cluster_server table, the ip_address column. Be sure to replace the IP address only for the line where the old one is present:

images/download/thumbnails/160480352/image2016-8-19_15_9_2.png images/download/attachments/160480352/image2016-8-19_15_9_45.png

Update management

  • Edit <install_dir>\Management\conf\safeq.properties – set the new IP address in the entry "safeq.network.address".

  • Edit <install_dir>\Management\tomcat\conf \server.xml – replace all occurrences of the old IP address with the new IP address (use the search and replace function in your text editor)

Start some YSoft SafeQ services again

  1. Start the following YSoft SafeQ services again:

    1. The YSoft SafeQ Management Service service

    2. The YSoft SafeQ LDAP Replicator service

      1. You can use the following PowerShell script to perform the task

        Start-Service YSoftSQ-Management; Start-Service YSoftSQ-LDAP


Update the configuration of the remaining services

Configure Spooler Controller to use the new IP address.

Change the IP address of the Site Server in the operating system.
Replace the IP address in the spoc.conf file.

  • Edit <install_dir>\SPOC\conf\modules\spoc.conf and set the new IP address in the property:

    • smartQ-server-ip= %NEW_IP_ADDRESS%

If YSoft SafeQ Management Server's IP address was changed too, then also configure the parameter serverIP1=%NEW_MS_IP% at the end of the file. If there are more YSoft SafeQ Management Servers, then change all serverIP properties on all servers accordingly.

If you have YSoft SafeQ 6 MU14 or older, replace the IP addresses in the server.xml file.

  • Edit <install_dir>\SPOC\tomcat\conf\server.xml and replace all entries of the old IP address with the new IP address (search and replace).

    This file is not present in SafeQ 6 MU15 and newer.

Replace the IP address in the TerminalServer.exe.config file

  • Edit <install_dir>\SPOC\terminalserver\TerminalServer.exe.config and set the new IP address in the properties:

    • <add key="networkAddress" value="%NEW_IP_ADDRESS%" />

    • <add key="imsProxyAddress" value="%NEW_IP_ADDRESS%:7348" />

imsProxyAddress also contains the port number. If the port was changed too, replace the default 7348 port accordingly.

Open the web interface of YSoft SafeQ Management Server (use the first node in the case of the Management Server cluster) and go to Devices => Spooler Controller groups

  • Locate the SPOC where the IP address was changed, and click Edit.

  • images/download/attachments/160480361/spocedit.PNG
Replace the Network address with the new one.
  • images/download/attachments/160480361/spocedit2.PNG
Delete the SPOC's cache by deleting the folder <install_dir>\SPOC\SpoolCache

If YSoft SafeQ Payment System is installed on this server, update paymentSystemApiUrl

  • In the YSoft SafeQ Print Management interface, system update paymentSystemApiUrl to reflect the new IP address.

Update FlexiSpooler

  • No update required.

Update Workflow Processing System

  • No update required.

Update Mobile Print

  • In <install_dir>\MPS\Service\conf, update the file controlerIPs.config. Update the single entry to reflect the new IP address.

Update Mobile Integration Gateway

  • In <install_dir>\MIG\bin\ update the file ConnectorService.exe.config. Update the single entry to reflect the new IP address.

Apply changes

It is recommended to reboot the server with the changed configuration (make sure the new IP address is active).

If a reboot is not possible, you will need to follow these steps:

  1. Stop all YSoft SafeQ services if they are not stopped already.

    1. You can use the following PowerShell script to perform the task:

      Get-Service *YSoft* | Stop-Service

  2. Start YSoft SafeQ services with the Automatic startup type again.

    Do not start the YSoft SafeQ Spooler Controller Group Service service. It will be started by the YSoft SafeQ Spooler Controller service when the proper configuration is ready.

    1. You can use the following PowerShell script to perform the task:

      Get-Service *YSoft* | Where-Object {$_.Name -ne 'YSoftSQ-SPOCGS'} | Start-Service

Verify the SPOC has the correct functionality according to the article YSoft SafeQ SPOC Health Check

Reconfiguration of the Site Servers – Connection to the New IP Address of the Management Server

  1. Edit <install_dir>\SPOC\conf\modules\spoc.conf

    1. Replace the IP address of the affected Management Server in the corresponding serverIP parameter at the end of the file.

    2. If you had a two-nodes Management Server cluster before you started with the procedure, also replace ServerGUID for the replaced server with the new IP address. The correct ServerGUID can be obtained from the web interface of the node with the new IP address.

  2. Also reconfigure the YSoft Infrastructure Service Proxy service settings.

    YSoft Infrastructure Service Proxy service is available only on Site Servers. If you are changing settings on a Management Server, skip this section and continue with step 3.

    If you have YSoft SafeQ 6 MU14 or newer build:

    1. stop the YSoft Infrastructure Service Proxy service.

    2. move to the <install_dir>\SPOC\ims\ directory and edit the application.properties file.

    3. replace the old IP address of Management Server with the new IP address of the server and save changes.

    4. start the YSoft Infrastructure Service Proxy service again.

    If you have YSoft SafeQ 6 MU13 or older build:

    1. Stop the YSoft Infrastructure Service Proxy service.

    2. Move to the <install_dir>\SPOC\ims\ directory and start the following command from the Command line.

      prunmgr.exe //ES//YSoftImsProxy

    3. The YSoft Infrastructure Service Proxy Properties dialog opens.

    4. Move to the Java tab and check the value of the -DinfrastructureServiceAddress parameter inside Java Options:

      • if the old IP address of Management Server is there, replace it with the new IP address of the server and confirm the changes.

    5. Start the YSoft Infrastructure Service Proxy service again.

  3. Reinitialize the connection from the Site Servers to the Management Servers.

    1. If you did not recover the database from the backup in the previous steps, then a restart of the Spooler Controller service is sufficient for re-initialization:

      1. Standalone Site Servers:

        • restart the Spooler Controller service

      2. Site Servers that are part of a SPOC group:

        • perform a restart of the Spooler Controller service only on one server at a time – once the service has restarted and the SPOC comes online on the Management Server (YSoft SafeQ management interface > Devices > Spooler Controller Groups), wait approximately 5-10 minutes, and then you can proceed with restarting the Spooler Controller service on the next server in the same SPOC group.

    2. If you did recover the database from the backup in previous steps, a cache deletion and a restart of all services is necessary:

      1. Standalone Site Servers:

      2. Site Servers that are part of a SPOC group

Other Required Configuration

  1. If a SPOC on the server with the new IP address is part of a Spooler controller group, then the SPOC cache must be deleted and the whole SPOC group must be restarted.

    1. The other members of the SPOC group must learn about the new IP address. They learn it only during their startup.

    2. Follow the section "How to safely restart SPOC group with cache deletion" from the chapter How and When to Restart a Standalone SPOC and SPOC Group

  2. If a SPOC on the server with the new IP address is part of a Spooler Controller group and the parameter enableEtcd is enabled, then the etcd cluster in Terminal Server must also be reconfigured.

    1. Follow Reconfiguring or Recovering an etcd Cluster in Terminal Server.

  3. Reinstall all Embedded and hardware Terminals that connect to the server with the new IP address.

  4. Reconfigure all print drivers (or YSoft SafeQ FlexiSpoolers) to connect to the new IP address.

    1. All print drivers and YSoft SafeQ FlexiSpoolers that were connected to the SPOC server with the old IP address must be re-connected to the new IP address

Troubleshooting

If a Terminal Server, Mobile Print, and FlexiSpooler are not running correctly, check the logs. You might see that they are either still listening on the old IP (Terminal Server) or trying to connect to the old IP address (FlexiSpooler and Mobile Print). To fix this, do the following only on the affected server:

  1. Stop all SPOC services, FlexiSpooler, TerminalServer service and Mobile Print services.

  2. Delete the SPOC's cache by deleting the folder <install_dir>\SPOC\SpoolCache

  3. Edit <install_dir>\FSP\Service/locations.config. Replace the old IP address with the new IP address.

    • after the first startup, it should update to 127.0.0.1

  4. Edit <install_dir>\MPS\Service\conf\controllerIPs.config. Replace the old IP address with the new IP address.

  5. Start the SPOC services and then the remaining services. Everything should work normally now.