# Installing and Configuring IQService IQService, also referred to as the Integration Service, is a native Windows service that enables SailPoint to participate in a Windows environment and access information only available through Windows APIs. It is a lightweight service that must be installed on any supported Windows Server that has connectivity to the target systems you want to manage in SailPoint. ## Prerequisites > [!NOTE] > > **Software Requirements** > > | Operating Systems | .NET Framework | > | --- | --- | > | Microsoft Windows Server 2019; Microsoft Windows Server 2016 | .NET Framework version 4.8 Minimum; .NET Framework version required 4.5.2 Supports; .NET Framework version 4.7.1 | > > > **Note** > > > > IQService for SailPoint is compatible with lower versions of .NET Framework (4.5.2 onwards). SailPoint recommends using the latest version of .NET Framework 4.8 to align your environment with future releases of this service. > [!NOTE] > > **Hardware Requirements** > > This is the minimum hardware requirement for a basic working instance of IQService with an average processing load when used with one application. The requirement proportionately increases with an increase in the request processing load and number of applications it serves. > > | Component | Recommended Hardware Requirement | Minimum Hardware Requirement | > | --- | --- | --- | > | CPU | 8-Core | 4-Core | > | RAM | 16 GB | 8 GB | > | Free Disk Space | 50 GB | 250 MB | > [!NOTE] > > **Service Account** > > The service account defined in the SailPoint source that connects to IQService is used for provisioning operations, aggregation (terminal services attributes and Skype attributes), and server-less binding for respective target system. > > However, the account defined for the IQService Log On as an account in Windows is used for the before/after scripts where PowerShell is being used. If the source's service account is not used, then the PowerShell session is opened under the service account credentials of IQService. ## Installing IQService 1. Download the Integration Service from SailPoint via a source that requires it. > **Screenshot** > > [![Download IQService from the source]()]() 2. Run the following commands to install the IQService Windows service. - Install IQService for non-TLS communication with SailPoint: ```text IQService.exe -i ``` This command installs an IQService instance named `IQService-Instance1` and uses port 5050 if available. - Install IQService for TLS communication with SailPoint: ```text IQService.exe -i -o ``` This command installs an IQService instance named `IQService-Instance1` on the specified TLS port. > **Note** > > For more details on the requirements and procedure to set up TLS Communication and Client Authentication, refer to [Configuring TLS and Client Authentication for IQService](). - Install IQService for both TLS and non-TLS communication with SailPoint: ```text IQService -i -p -o ``` This command installs an IQService instance named `IQService-Instance1` on the specified TLS and Non-TLS ports. 3. Unzip the downloaded **IQService.zip** archive into the created or desired location. For example, `C:\SailPoint\IQService\` > **Note** > > Verify the DLLs are trusted by checking the properties of the DLL files. 4. Start the service either from the Services Applet or from the command line by running the following command: ```text IQService.exe -s ``` > [!NOTE] > > **IQService Commands** > > In addition to the commands -i to install and -s to start, other command line options with IQService include: > > | Command Line Options | Description | > | --- | --- | > | \-d | Run in console mode | > | \-i | Install a service. Refer to [Registering IQService](<#registering-iqservice>) for more information. | > | \-k | Stop the service | > | \-p | Update the port (requires a service restart) | > | \-r | Remove the service | > | \-u | Uninstall the service. Removes the service components and clears the registry entries. | > | \-s | Start the service | > | \-t | Restart (stop/start) the service | > | \-v | Print version information | > | \-l \\\ | Trace Level 0-3; 0=off 1=error 2=info 3=debug | > | \-f \\\ | Trace the file name. Defaults to the system32 directory.
Enter the full path with a filename to log to a different path. For example: `iqservice -l 3 -f "C:\Sailpoint\IQService\iqtrace.log"` | > | \-a | Registers a domain user for Client Authentication. Pass the domain user name in `msDS-PrincipalName` (domain\\user) format. Multiple users can be registered in a single command by separating them with a semicolon ( ; ).
This command appends users to existing registered users. For example: `-a "Acme\John.Smith; Acme\Joe.Phillips"`
Ensure that the exact same user name is configured on the source for this feature to work.
To list existing registered users, run the command with the `list` parameter.
For example: `-a list` | > | \-x | Unregisters a user from the Client Authentication Users List. Pass the domain user name in `msDS-PrincipalName` (domain\\user) format. Multiple users can be registered in single command by separating them with a semicolon ( ; ).
For example: `-x "Acme\John.Smith; Acme\Joe.Phillips"`
To list existing registered users, run the command with the `list` parameter.
For example: `-x list` | > | \-o \\\ | TLS port for communication between IQService and SailPoint. This port accepts communication over TLS only. | > | \-j \\\ | Enforce the specific TLS version for communication between IQService and SailPoint.
Supported values are:
\- `TLS1.2` (Default)
\- `TLS1.1`
\- `TLS1.0` | > | \-m \\\ | "Issued To" (CN of Subject) of the X.509 certificate. It is applicable to communication between IQService and SailPoint. This overrides the default lookup text for IQService to search for the X.509 certificate on the machine. By default, IQService looks for the X.509 certificate issued to FQDN of current machine.
For example: `-m example.com` | > | \-? \| h: | This is for help output | > [!NOTE] > > **Configuring Default TLS Version** > > The SailPoint IQService supports the `default` configuration for `tlsVersion`. To enable this configuration, execute the `IQService.exe -j` default command. > > With this configuration, the operating system selects the best available protocol. This configuration requires that `SystemDefaultTlsVersions` is enabled on the IQService machine. If it is not enabled, then IQService falls back to the highest commonly supported version from the predefined list of TLS versions. ## Registering IQService The `IQService.exe -i` command installs and registers the service with the new registry path `HKEY_LOCAL_MACHINE\SOFTWARE\SailPoint\IQService Instances\IQService-Instance1` with the following keys: | Keys | Description | | --- | --- | | port | Port to listen | | tracefile | Path to the tracefile | | tracelevel | 0 (off)
3 (verbose) | | maxTraceFiles | Maximum number of Trace log files that must get created before overwriting the older files | | traceFileSize | Maximum file size of a trace file in bytes. A new file is created when the current file exceeds this limit | | clientAuthUsers | If you configure IQService with client authentication, the IQService user is displayed with this key. | | tlsPort | If you configure the TLS port, the IQService is set up for the communication over TLS. | The IQService accesses only the IQService-related keys in the registry editor, and installs or uninstalls successfully. ## IQService Fallback Implementation In information technology, the term fallback refers to a backup solution to prevent the total failure of a system. The fallback solution commonly has a reduced or limited functionality but is still capable of operating the most important functions for a certain period, to allow time for operation of the system to be brought fully online again. After the primary system is restored, the fallback solution is deactivated and normal operation is resumed. IQService now allows you to install a secondary instance (fallback instance) of the primary service running on an IQService host machine. This secondary IQService instance takes over only when a primary IQService instance is down and not serving the requests coming from SailPoint. In SailPoint, any request from user gets routed through VA (Cloud Connector Gateway). VA takes care of sending request to the appropriate request handler. Here if primary IQService instance is down, then the request processing is redirected to secondary IQService instance by the VA. > [!NOTE] > > Once the primary IQService is restored or working as expected, the VA automatically starts redirecting requests to the primary IQService. [![IQService fallback]()]() The secondary service is not considered as a load balancer service or a high availability service. The secondary service works as a fallback service in case of failure of the primary IQService. > [!NOTE] > > The secondary IQService is used to serve requests when the primary IQService is down during upgrades. The secondary IQService handles manages requests if the primary IQService instance crashes and can handle the next requests until the primary service is running. However, the primary IQService must not be stopped purposefully and you should not keep the secondary service running to handle requests from SailPoint. If the primary IQService is stopped by running the `IQService -k` command, the secondary IQService is also stopped. ### Installing the Secondary IQService Instance The secondary IQService is automatically installed on the same host but with a different port (the installer uses another available port) as the primary IQService. 1. `IQService.exe -i` - This command installs two instances of IQService. During installation it creates a **IQService-Instance1-Secondary** directory inside the installation directory of IQService. It copies all files present in the installation directory to that directory. It is the installation directory for the **IQService-Instance1-Secondary** service. 2. `IQService.exe -i -b` - This command allows you to install only one instance of IQService. This command is recommended only you have a load balancer configured to take care of failures in the running service. 3. `IQService.exe -s` - If the secondary service is installed, this command starts both instances of IQService. 4. `IQService.exe -k` - If the secondary service is installed, this command stops both instances of IQService. 5. `IQService.exe -t` - If the secondary service is installed, this command restarts both instances of IQService. > [!NOTE] > > When the Primary service is started, stopped, or restarted either from a command or through a services console, the operation is performed on both the instances. After installation, you can configure different ports or TLS ports. > [!NOTE] > > **Configuring the Secondary IQService Instance** > > | Command | Description | > | --- | --- | > | `IQService.exe -v` | Print version information | > | `IQService.exe -p ` | Update the port number of secondary service | > | `IQService.exe -o ` | Update the TLS port number of secondary service | > | `IQService.exe -t` | Restart the secondary service. | > > For TLS, the secondary service uses all the configuration defined in primary service (except the TLS Port). > > The secondary service uses the log level defined in the primary service. The file name is the same as that of the primary service. The only change is the file is in the installation directory of the secondary service. > > > **Note** > > > > - It is recommended that you shouldn't stop the secondary service. > > - If the logon user is changed for the primary service, then you need to update the logon user for the secondary service to the same new user. > [!NOTE] > > **Secondary IQService Information** > > In SailPoint, the Test Connection call confirms that all the required components are up and running. With this new feature, the source sends secondary IQService port information to SailPoint. This information is stored in the source XML file, and it is utilized whenever there is a need to connect to a secondary IQService. There is no indication in the user interface that a secondary IQService exists. > > > **Note** > > > > - Secondary IQService details are not available on UI. > > - Secondary IQService details are updated in source xml file only after first Test connection call. ## Upgrading IQService To upgrade, you must uninstall the previous version and then install the new version. SailPoint also recommends backing up the current installation before uninstalling to aid with troubleshooting the new version, should issues arise. - To determine the existing (old) version, run the following command: ```text IQService.exe -v ``` - To uninstall the existing (old) version, run the following command: ```text IQService.exe -u ``` - Run the following command to install a new version: ```text IQService.exe -i ``` ### Upgrading IQService to the Latest Version 1. Take the backup of the existing IQService installation. 2. Stop the service either from the Services Applet or from the command line by running the following command: ```text IQService.exe -k ``` 3. Uninstall IQService using the `IQService -u` command. 4. Extract the latest IQService in the installation directory. 5. Install the new IQService using the `IQService -i` command. 6. Start the IQService. > [!NOTE] > > If you have executed the **IQService Public Key Exchange** task for the existing IQService then SailPoint recommends that you follow the instructions mentioned to install and register a new IQService.