Managing your service

With iCR installed, you can begin to analyze your projects after completing some basic configuration using the icr command which was installed along with your package. This command is used to configure some essential parameters, stop/start the service, and set up other options. The usage statement for the command is as follows: icr [-a] [-d] [-l] [-v] [-p] [-vv] [-h] <arg> ? [-c <cmd>]

The options can be combined in a single command. However, the -c <cmd> should always go last since it is used to invoke server operations. We’ll be looking at each option in detail.

But, before you can start using your server, there are 3 important configuration values that need to be established. The first concerns the license that you received from OpenRefactory. The license enables iCR for the duration and OBLoCs capacity that you purchased from OpenRefactory. It must be set before analyses can proceed. Establish your license by entering: icr -l <Your license key>\

where <Your license key> is the string that you received from OpenRefactory. It will look something like this: GHTG-WK9M-9HSK-J9OR.

The second value which needs to be set is the string which tells iCR the URL that you will be giving to your users to access iCR. That command will look like: icr -a "<URL-String>"

where <URL-String> is the URL entered information the browser to access your iCR server. For example, if you assigned the server a URL of iCR-for-all.mycompany.com, then the command would be: icr -a "icr-for-all.mycompany.com"

If you do not assign a URL to the server, you may also simply use its IP address directly as, for example: icr -a 192.1.2.123

NOTE: OAuth is required to authorize access to your server as covered in the User Guide. It is essential that the URL or IP address that you set here matches the callback address in the OAuth configuration.

The third value is key to maintaining a secure connection to your iCR server from your Users' browsers. iCR uses https to connect. https uses Transport Layer Security (TLS) to manage the encryption and that requires installing a certificate on the server. It is expeected that, when iCR is installed and assigned a URL, the administrator also obtains an SSL certificate to use for iCR. In that case, the certificate and SSL key must be configured into icR. The icr -c ssl command is used for that and is described below.

NOTE: In the event that the administrator chooses to not secure a certificate for iCR, then iCR will use a self-signed certificate. Using a self-signed certifcae usually triggers a warning from the browser as discussed in the Connecting to the Navigator section of the User Guide.

Below are the details for each of the individual icr commands.

icr -a <URL-String>

The -a option is used to provide iCR with the URL to the server. If you are using a cloud-based repository, such as GitHub, there needs to be a way for GitHub to access the iCR server from the cloud, so you need to provide a public address to allow GitHub to reach the iCR server. You must configure iCR with the URL that you assigned for th server. If you have not assigned a specific URL, you may use the server's IP address. Entering icr -a without an argument will display the current URL being used.

As an example: icr -a "icr-for-all.mycompany.com"

or: icr -a 192.1.2.123

icr -d <directory-path>

The -d option is used to anchor iCR with the point in your host file system where you plan to store projects for local access. While you may access GitHub, GitLab or Bitbucket to process repositories managed by those systems, you may also want to analyze and review projects resident in your local file system. You can also include directories that may be attached via a network attached storage and mounted into your file system. The default anchor point is the /home directory under which user directories are normally located within Linux. Entering icr -d without an argument will display the current anchor point being used.

As an example: icr -d /home/projects

icr -l <license-key>

The -l option is used when there is a need to update or replace your activation license. The license is activated when you initiaite your first analysis. Should your license expire due to the tie limit being reached or capacity exceeded, OPenRefactory can update your license and add additional time or capacity. However, if there is a ned to repalce the license or wwhen setting the license following package installation, then the license is set using this command. Entering icr -l without an argument will display the current license being used.

As an example: icr -l GHTG-WK9M-9HSK-J9OR

icr -p <port#>

Users connect to iCR via their browser. The norwser opensan https connection to the server via the IP addres or DNA name of their server. The pot usedby iCR, by default if TCP port 3001. Not all deployments will find this port acceptable and so the -p option is used to redirect iCR to use a different port for connection. Entering icr -p without an argument will display the current port being used.

As an example, set the port to 5050: icr -p 5050

icr -v

It is sometimes important to know what version of iCR software is being run. This command displays the current version of the software.

icr -vv

This is the verbose form of the version command. This command displays the current version of the software along with details about the various components in a particular package. It can be useful of you need to report a problem to Openrefactory.

As an example: icr -vv

/Unified$ icr -vv
icr version                5.0.0
icr nav-rev version        5.0.0
icr engine version         5.0.0 
icr worker version         4.2.0 

icr -h / icr ?

Displays the extended usage form for the icr command:

icr [-a] [-d] [-l] [-v] [-p] [-vv] [-h] <arg> ? [-c <cmd>]
   Where:
        -a <IP_ADDRESS>	                        # define the server's public IP address
        -d <MOUNT_DIR_PATH>                     # define a new root directory
        -l <LICENSE>                            # change the license key
    -    v <VERSION>                            # output the current version
        -p <PORT>                               # change the iCR port number
        -vv <VERBOSE>                           # output the current version and more details
        -h                                      # output this help
        ?                                       # output this help
        -c <cmd>
           Where <cmd>:
                start                           # start the service
                stop                            # stop the service
                ssl                             # ssl certificate wizerd

icr -c <cmd>

The previous options were used to update or change some configuration values. To actually operate iCR you use the -c <cmd> option. There are three specific values that can be used to control your server’s operation:

1. icr -c start

   This is the command that is used to start the iCR server. It assumes that you have successfully installed the service on your host machine using install-icr. It starts the Docker image from scratch. The default passphrase will be used to access the Navigator for the first time. The default string is: icr. You will be prompted to change it once you access the Navigator.

2. icr -c stop

   The stop command is used to stop the running instance of iCR. The Docker container is stopped and any activity in progress is interrupted. For example, if the service is stopped during an analysis, that analysis will be abandoned. All results from previous analyses, however, are still available and can be viewed again once the service is restarted using the start command.

3. icr -c ssl

   As noted above, iCR expects secure communication between the browser and the server. It uses https to achieve this and https requires a certificate and key to be installed onto the server. The icr -c ssl command does that. To execute this command the server must be stopped. If it is still running, the command will ask you to stop the server first. Executing the command invokes a simple input exchange asking if you want to continue using the default self-signed certificate or if you have produced one that you want to install into icr. It looks like this: SSL Certificate Setup Wizard ------------------------------------ Please choose an option: 1) Use a self-signed certificate 2) Provide your own certificate and private key Enter your choice (1 or 2): If you have acquired a certificate for iCR then enter 2 as your choice. This gives you the chance to enter the path names to both the certificate and key files: Enter your choice (1 or 2): 2 Please provide the paths to your ssl certificate and private key. Path to your certificate file (must end with .pem): /home/or-testuser/cert.pem Path to your private key file (must end with .pem): /home/or-testuser/key.pem Your certificate and private key have been stored. If the file paths do not resolve correctly you will see an error: Please provide the paths to your ssl certificate and private key. Path to your certificate file (must end with .pem): /home/cert.pem Path to your private key file (must end with .pem): /homekey.pem Error: One or both files do not exist. Please check the paths and try again.