# How to Setup a Remote Connection to Illumina Run Manager on the MiSeq i100 Series Instruments

## **Background**

The Illumina Run Manager (IRM) remote user interface (UI) allows users to plan sequencing runs, requeue analysis, configure instrument settings, and other functions from a remote computer connected to the same network as the MiSeq i100 Series instrument.

For **Windows** users, Illumina Tech Support can provide a command line program to assist in configuring the client computer and installing the appropriate certificate files. Contact [Illumina Tech Support](https://www.illumina.com/company/contact-us.html) to request the appropriate files.

For **MacOS** or **Linux OS** users, see manual installation instructions below.

### **Configure the MiSeq i100 Series Control Software**

The MiSeq i100 Series is pre-configured to prevent any incoming connection requests on all ports. To allow remote connections to Illumina Run Manager, the Control Software must to be configured to allow incoming connections on ports **80** and **443**.

1. Login to the Control Software as an **Administrator** user
2. Select the drop-down menu in the top-left corner, then select **Settings**.
3. Under Network, select **Firewall Settings**.
4. Select the checkbox next to 'Enable network ports 80 and 443 for remote access' and select **Save**.
5. The configuration process can take several minutes to complete, do not turn off the instrument during this process as it can cause Software configuration issues.

![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-aaefbd124d908f153b7ed6136a7997ebdce790e0%2Fimage1.png?alt=media)

### **Find your MiSeq i100 Network Parameters**

The following information can be found in the MiSeq i100 Control Software Settings, under **Network Settings**:

* The MiSeq i100 instrument **IP address** (e.g., 10.14.64.55).
* The MiSeq i100 instrument name **hostname** (e.g., sh00033).
* The MiSeq i100 instrument **domain name** (e.g., illumina.com).

  * This is an optional field and may not be specified depending on the instrument network settings

  ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-2315ac24077aff696e4d2f137b7d8af119772cb0%2Fimage2.png?alt=media)

**Figure 1**: Network Settings menu showing instrument configured with hostname and domain name where the FQDN will be hostname.domainname.

**Using the IRM Certificate Installer (Windows Only)**

1. Download the IRM\_Certificate\_Installer\_Windows\_v0.4.zip compressed file to the client computer.
2. Right-click on the compressed file and select **Extract All...**, then follow the prompts to extract the README.txt and executable file to the client computer.
3. Right-click on the executable and select **Run as Administrator**.
   1. If prompted, select **Yes** to confirm running executable as Administrator.
4. When prompted by the program, input the instrument **hostname**, **IP address**, and **domain name** (if applicable).
5. The program will perform the steps to update the client computer's `hosts` file, test the connection to the instrument, and then install the required security certificates.
6. If the program is successful, it will present the Illumina Run Manager remote connection URL.
7. Copy and paste this URL into the Address bar in the internet browser and confirm that Illumina Run Manager remote UI is accessible.

**Manual Installation Instructions (Windows, MacOS and Linux)**

If the remote computer is running **MacOS** or **Linux**, or the Windows program is not successful, see the following instructions for manual configuration.

### *Configuring the hosts file (Windows Computer Instructions)*

1. Log into the computer with an account that has Administrator privileges.
2. Open a text editor such as Notepad or Notepad++ by right clicking the icon and selecting **Run as administrator.**
3. From the open text editor, browse to \*\*C:\Windows\System32\drivers\etc\*\*and open the **hosts** file.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-1328571d1956df4c43ac5340ccdd59e7fcfcbf87%2Fimage3.png?alt=media)
4. Add the instrument IP address and FQDN as a new entry at the end of the **hosts** file:\
   `{your MiSeq i100 IP Address} {your MiSeq i100 FQDN}`
   1. Use a tab or spaces to separate the IP address and FQDN.
   2. Do **NOT** include the # at the start of the line as this comments out the entry and prevents IP address resolution.
5. Example:\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-a6fa991824dbd24a21477ad8b312d74aa2df23f0%2Fimage4.png?alt=media)
6. Save the new `hosts` file. If the file is not able to save directly to the ../etc directory, see the following steps:
   1. Save the file as hosts.txt to the computer **Desktop**.
   2. Rename the hosts file in the ../etc directory as hosts.bak.
   3. Copy the hosts.txt file from the **Desktop** to the ../etc directory.
   4. Right click on hosts.txt and select **Rename**, then delete just the .txt extension.
   5. Follow the prompts to confirm you want to remove the extension.
   6. The final file should be a new `hosts` file with no extension.

### *Configuring the hosts file (Mac or Linux Computer Instructions)*

1. Log into the computer with an account that has Administrator privileges.
2. Open a terminal window and enter the following command, then press Enter
   1. sudo nano /etc/hosts
3. Enter the sudo password for the user to allow edit access to the file. A screen similar to the following appears:\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-d22d37de26cffebde1aa1026599597ae66bd82ae%2Fimage5.png?alt=media)
4. Use the arrow keys to move the cursor to the bottom of the file.
5. On a new line, add the **instrument IP** address and **FQDN**, separated by a tab or spaces. In the following example, the **IP address** is 10.16.28.65 and **FQDN** is sh00033.illumina.com:
   1. Do **NOT** include the # at the start of the line as this comments out the entry and prevents IP address resolution.\
      ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-4c7a1c206ccc94a629f4f4be59420632e7ac7c96%2Fimage6.png?alt=media)
   2. Press **ctrl+O** to overwrite the existing file, then press **Enter** to confirm the overwriting. This saves changes to the **hosts** file.
6. Press **ctrl+X** to exit the nano editor.
7. ***Mac Only*** - Update your browsers DNS records to make these changes go live in the browser by entering the following command, `sudo killall -HUP mDNSResponder` then press Enter

### *Verify Instrument Address Resolution (All Operating Systems)*

1. Open a browser and enter the following URL, replacing \[FQDN] with the instrument `hostname` or hostname.domainname as appropriate:\
   https\://\[FQDN]/v1/instruments/public/ca
2. Confirm that access to the instrument. If successful, the following output appears in the browser:\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-ee80291e1e260b392ab2d0cfab8b72044362ed4b%2Fimage7.png?alt=media)
3. Hit the Advanced button in the lower left and click **Proceed to sh00033.illumina.com (unsafe)**. The browser shows the FQDN was entered in the URL in place of *sh00033.illumina.com*. The resulting page should show {"edgeOSRootCertificate": ... as shown in the example image:\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-1a70327c9fa6426bd8ce3b66f5a5d820f71708e6%2Fimage8.png?alt=media)

## **Create a Trusted Self-Generated Root Certificate**

The MiSeq i100 Series is designed to utilize TLS certificates to securely connect to the instrument from any device on the same network (refer to [Product Documentation](https://support.illumina.com/downloads/miseq-i100-series-product-documentation.html) for more information). For users that do not have access to TLS certificates, a self-generated root certificate may be used to connect to the instrument through IRM. To generate the certificate, use a computer that is connected to the same network as the instrument. It is only required to trust the certificate one time per instrument and all remote computers can use that same certificate.

Instructions for trusting the certificate vary by operating system.

Any time the software is reinstalled or First Time Setup (FTS) is performed, a new trusted root certificate must be created.

### *Windows Computer Instructions*

1. Open PowerShellby typing **powershell** in the Windows search bar, right-click the icon and select **Run as administrator**.
2. In the PowerShell terminal, enter the following command and press **Enter**:
   1. cd \~\Documents
3. Enter the following command and press Enter to retrieve the certificate. Replace *sh00033.illumina.com* with the instrument FQDN:
   1. `$rootCert = (Invoke-WebRequest -UseBasicParsing -Uri "http://sh00033.illumina.com/v1/instruments/public/ca" | ConvertFrom-Json).edgeOSRootCertificate`
4. Enter the following commands and press **Enter** after each one to save the certificate to a file and import it into the Trusted Root Certificates store:
   1. `$certBytes = [System.Convert]::FromBase64String($rootCert)`
   2. `$certContent = [System.Text.Encoding]::UTF8.GetString($certBytes)`
   3. `$certContent | Out-File -FilePath .\edgeosRoot.crt`
   4. `Import-Certificate -CertStoreLocation Cert:\LocalMachine\Root\ -FilePath .\edgeosRoot.crt`
5. The self-signed root certificate is downloaded to the local computer, in the Documents folder, and added to the Trusted Root Certificates store.
6. Confirm that access to the instrument in a browser using the following URL, replacing *sh00033.illumina.com* with the instrument FQDN:\
   <https://sh00033.illumina.com>
7. If successful, the following login screen appears in the browser:\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-f24ea039f0949770ef91e2a45a47f3eecf002b0d%2Fimage9.png?alt=media)
8. The certificate is saved to the Documents folder (i.e. C:\Users{username}\Documents) and is named edgeRoot.crt.

The certificate must be added to the trusted certificate store on all Windows computers that require remote access to the instrument. Refer to the operating system instructions for information about adding certificates to the trusted root store.

### *Linux and Mac Computer Instructions*

* Open **Terminal**, enter the following command, replacing *sh00033.illumina.com* with the instrument FQDN, to save the certificate as a file called sh00033.crt:
  * `curl -k https://sh00033.illumina.com/v1/instruments/public/ca | jq -r ".edgeOSRootCertificate" | base64 --decode > sh00033.crt`\
    \&#xNAN;*Note: The .crt extension is required for the certificate to be properly added in the next steps.*
* **Mac OS**: Enter the command below to add the certificate to the trusted store, replacing *sh00033.crt* with the filename used in Step 1 above:
  * `sudo security add-trusted-cert -d -r` trustRoot `-k /Library/Keychains/System.keychain sh00033.crt`
* **Linux**: Enter the commands below to add the root CA certificate to the trust store, replacing *sh00033.crt* with the filename used in Step 1 above:

  * `sudo apt-get install -y ca-certificates`
  * `sudo cp sh00033.crt /usr/local/share/ca-certificates`
  * `sudo update-ca-certificates`

  *Note: Some software (e.g., Chromium, Chrome, Firefox, etc.) may not use the system-wide certificates, but rather must have the certificate imported into their own certificate store (see example below).*

The certificate must be added to the trusted certificate store on all Mac or Linux computers that require remote access to the instrument. Refer to the operating system instructions for information about adding certificates.

###

### *Install Root Certificate Authority in Chrome/Chromium (Linux and Mac)*

1. Open the Settings window.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-af5d6e8cc446b8756a112592d9cd01d93438c061%2Fimage10.png?alt=media)
2. Select **Privacy and security** in the menu on the left side, scroll down and select the **Security** button.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-e362fff1ae19ffe95aa236419e0d9a5b5d00f375%2Fimage11.png?alt=media)
3. Scroll down and select the **Manage certificates** button.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-560027fa8491c53119d5ca313c2c441b5b9b4077%2Fimage12.png?alt=media)
4. Select the **Authorities** tab and click the **Import** button.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-4aa4927cf71f2aceda121341e5bb75034f9f1f60%2Fimage13.png?alt=media)
5. Find the certificate saved in the previous steps, select it and click the **Open** button.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-1c25a886dc356e9131e2bee57a54db3b55be069f%2Fimage14.png?alt=media)
6. Check the **Trust this certificate for identifying websites** option and click the **OK** button to install the certificate.\
   ![](https://761066130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGM9W2DuBTgEXv1ClCm8H%2Fuploads%2Fgit-blob-3669aa1f0b9da296595b99c59e7f8f54f885e989%2Fimage15.png?alt=media)

\
\
\ <br>

|                                                                                                                                                                                                                                                                                                                                                                        |
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| *For any feedback or questions regarding this article (Illumina Knowledge Article #9334), contact Illumina Technical Support* [*techsupport@illumina.com*](mailto:techsupport@illumina.com?subject=Question%2FFeedback%20Regarding%20Illumina%20Knowledge%20Article%20#000009334%20-%20Instrumentation%20\&body=Dear%20Illumina%20Technical%20Support,%0D%0A%0D%0A)*.* |