MANAGING YOUR SERVICE
With the files copied and the Docker image installed, you can begin to run the service. One of the items installed is the icrforpython command script. This command is used to stop/start the service, update critical parameters used by the service and to uninstall the software if you need to do that. The usage model for the command is as follows:
icrforpython [-a] [-d] [-l] [-p] [-v] [-u] [-h] ? [-c ]
The options can be combined in a single command. However, the -c should always go last since it is used to invoke server operations. We’ll be looking at each option in detail.
3.2.1 icrforpython -a
The -a option is used to provide iCR for Python with an IP Address for the server. Typically, the IP address for the server is determined using localhost. However, if you are using a cloud-based repository, such as GitHub, there needs to be a way for GitHub to reach the server from outside of the private platform’s possibly protected network. In that case, you would need to provide an external public IP address for your firewall to allow GitHub to reach the iCR for Python server. You can configure iCR for Python with the public IP address using this command. As an example:
icrforpython -a 192.1.2.123
3.2.2 icrforpython -d
The -d option is used to anchor iCR for Python 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. As an example:
icrforpython -d /home/projects
3.2.3 icrforpython -l
The -l option is used when there is a need to update or replace your activation license. This might happen if you need to move the service to another host. The license is activated when you first run iCR for Python (not when it was installed) and connect to the Navigator for the first time. After that, your service is node-locked to the host computer. Should your license become damaged or unusable, this is a way for us to provide you with a new license. As an example:
icrforpython -l GHTG-WK9M-9HSK-J9OR
3.2.4 icrforpython -p
The default passphrase for iCR for Python is set to: icrforpython. When you first login to the service, you use the default passphrase to gain access to the Navigator. If the passphrase is set to the default, you will be prompted each time you connect to the Navigator to change it from the default to some other practical passphrase. Using the -p option allows you to reset the passphrase back to the original default or a new default phrase as specified by the string that you provide. Just remember that, if you change the default, the Navigator will check to see if the default passphrase is in force and will continue to prompt you to change it. As an example:
icrforpython -p New_Pa$$word
3.2.5 icrforpython -v
It is sometimes important to know what version of iCR for Python software is being run. This command displays the current version of the software.
3.2.6 icrforpython -u “ ”
iCR for Python on Private Platforms can be executed as a step in an integrated CI/CD workflow. For Jenkins, a plugin is used. However, for GitHub Actions, a specific User’s GitHub App is used. The Navigator has the GitHub App behavior built in. However, the Navigator needs to communicate using secure APIs with GitHub for the integration to work. This connection is secured using a pair of pem keys.
This command must have a string with 2 arguments. The double quotes are required to encompass the 2 arguments needed for this command. The first, , is the name of the User’s GitHub App registered by a user for whom a CI/CD step is configured. Multiple GitHub apps may be registered with the same iCR server so that many distinct CI/CD workflows can be served by a single server.
The second argument, , is the path where the pem file may be found. The pem pair is created when the GitHub App is registered. See the document iCR - Workflow Integration User Guide v1.1 for details on how to use GitHub CI/CD workflows. The pem file is copied to /etc/icr-data for use by the Navigator.
As an example:
icrforpython -u “GitHubApp4iCR /etc/pemfiles”
3.2.7 icrforpython -h / icrforpython ?
Displays the extended usage form for the icrforpython command:
icrforpython [-a] [-d] [-l] [-p] [-v] [-u] [-h] ? [-c ]
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
-p < PASSPHRASE > # set a new default passphrase
-v < VERSION > # output the current version
-u “<GITHUB_APP>< PATH >”# add a user pem file for GitHub app
-h# output this help
?# output this help
-c < cmd >
Where < cmd >:
start # start the service
stop # stop the service
uninstall # remove the service and all associated files
activate # activate the license
3.2.8 icrforpython -c
The previous options were used to update or change some configuration values. To actually operate iCR for Python you use the -c option. There are four specific values that can be used to control your server’s operation:
icrforpython -c start This is the command that is used to start the iCR for Python 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 first time that start is invoked, the service will be node-locked to this host using the license provided in the package that you received. The default passphrase will be used to access the Navigator for the first time. The default string is: “icrforpython”. You will be prompted to change it once you access the Navigator.
icrforpython -c stop The stop command is used to stop the running instance of iCR for Python. 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.
icrforpython -c uninstall There may be cases where you wish to remove iCR for Python entirely from your host system. If so, run the uninstall command. This will remove all of the Docker information as well as the directories that were created as part of the install-icr process. All results from analyses will be removed. Please be certain that you want to remove everything if you decide to run this command. If you need to restore iCR for Python, and you have kept your original package, you can re-install the service using the install-icr command again.
icrforpython -c activate iCR is designed to work while the server is connected to the Internet. The internet is used to validate and check license parameters including your OBLoCs usage. Normally, the license is validated and checked for each analysis. However, in cases where the server may need to be isolated from the Internet, the license must be validated manually. Use the -c activate command for this. Details on this procedure are given in Section 3.2.9.
3.2.9 OPERATING ISOLATED FROM THE INTERNET
iCR is designed to work while the server is connected to the Internet. There are no code analysis functions that are performed remotely and all of your source code is protected within your Docker container. However, the Internet is used for 2 functions: one of them is to allow email messages to be sent for notification events and summaries. The other use is to validate the license to ensure that the server is authorized to execute iCR and to track the OBLoCs consumed. It is understood that there may be cases whereby you do not want your iCR server to operate while connected to the Internet. To enable this “isolated” operation, there is a process for activating your license and then allowing iCR to work “offline”.
The steps to operate in an isolated mode are:
Install iCR for Python as described in Section 3.1. The installation requires that you are connected to the Internet for the purpose of downloading the software.
Once the software is installed, your license will have been copied along with the other iCR software to its expected place in the file system. While still connected to the Internet, use the following command to activate your license: icrforpython -c activate
Running the command invokes the license management software causing your license to be activated. Once activated, the license duration “clock’ has begun.
You may execute any other icrforpython commands such as the -d command (see Section 3.2.2). Since you will become isolated from the Internet, access to remote repositories is not possible so you will likely need to use the local option for accessing your projects.
Once the command completes, your license is now active and you can isolate the server from the Internet. You may then initiate iCR operation using the icrforpython -c start command.
Although the server operates independently of the Internet, there must still be network access because your browser needs to be able to reach the iCR for Python server in order to communicate with the Navigator and Reviewer. Normally, you just need to enter the IP address of the server followed by the port 3002 (See Section 4.1 for how to connect). In the event that your browser may be accessing the server through a router providing NAT or other translation, then you must tell the server the IP address that the browser requires to reach the server. For this, use the icrforpython -a <IP_Address> command. See Section 3.2.1 for details on this command. iCR will operate in an isolated mode until the OBLoCs are depleted or the time duration on your license expires. Of course, features such as email notification and summary reports are not available to you while operating in this fashion. Should you need to update your license, you can work with OpenRefactory to refresh your license. However, to have the updated license become active, you would need to temporarily connect to the Internet again and rerun the icrforpython -c activate command.
3.2.10 OPENING PORTS
iCR for Python uses a browser interface to interact with the Navigator and the Reviewer. It may be that the host system for the service is behind a firewall or has security restrictions applied to it to limit network access. For the service to run correctly, a number of TCP ports must be open to the server. Some of these ports may already be open as they allow, for example, remote logins over SSH or other browser access. A couple of the ports are unique to iCR for Python. The ports that you need to have open are the following TCP ports:
22 – This is the SSH port to allow you to access your server. You use this to securely login into your host system to be able to run the iCR for Python commands.
80 – This is the regular HTTP port to allow browsers to access your server.
443 – This is the secure HTTPS port to allow browsers to access your server.
3002 – This port is used by your Browser to work with the Navigator.
3003 – This port is used by your Browser to work with the Reviewer.
Last updated