This and the following chapter cover a few important topics such as Jenkins CLI, Jenkins Rest APIs. You are already aware of how to control Jenkins manually using its UI. But sometimes you may need to control Jenkins programmatically through scripting languages or shell programs. In that case, you need to know how to use the programming interface provided by Jenkins and its command-line interface. This chapter focuses on how to interact with Jenkins using its CLI.
You are going to learn about some different common use cases where you are required to interact with Jenkins programmatically instead of manually.
Understanding the Jenkins CLI
Jenkins provides two kinds of interfaces—the Graphical User Interface(GUI), which we have already covered in this book, and the Command-line Interface (CLI), which you are going to learn about in this chapter.
Jenkins provides a different set of shell commands that you can run from shell programs, like the command prompt on Windows or the console shell on Linux-based systems. You can write batch programs or shell scripts to automate access to the Jenkins server. Let’s see in detail the different CLI commands Jenkins provides, how can we interact with the Jenkins server using these commands, and most importantly, how to provide authentication information to the Jenkins server to authenticate the Jenkins server access using CLI.
Jenkins provides us with many CLI commands, a list of which is available on the Jenkins CLI page.
Click the Manage Jenkins link available on the left side of the Jenkins dashboard. This will open the Manage Jenkins page.
Scroll down the page to find the Jenkins CLI link under the Tools and Actions section. Click the Jenkins CLI link, which will take you to the Jenkins CLI. This page shows a list of different commands and the purpose of each command.
How to Interact with Jenkins Using its CLI
This section explains how to perform basic operations through the CLI, like creating a job, running a build of a specific job, retrieving a list of all jobs, retrieving console output of a build, disabling a particular job, deleting a particular job, and more.
Before you start using the Jenkins CLI, you need to download jenkins-cli.jar. This JAR file provides the CLI client so you can access the CLI interface.
Click the jenkins-cli.jar link from the Jenkins CLI page to download the Jenkins-cli.jar file. After you click the link, the jenkins-cli.jar file will be downloaded.
I started my Jenkins server from my machine’s IPv4 address (192.168.43.10) and the default port 8080. Therefore, my Jenkins URL is http://192.168.43.10:8080, which I use to access my Jenkins server through CLI. Your Jenkins URL will contain either the localhost or your IP address along with the port. I keep the jenkins-cli.jar file in the D:JenkinsBookExamples folder, so the CLI commands have the jenkins-cli.jar path, written as D:JenkinsBookExamplesjenkins-cli.jar. You need to use your path on your machine.
How to Create a Job Using the Jenkins CLI
To create a new job in Jenkins, you need to specify the job name and the configuration XML based on the new job. A view is a way to organize jobs and content into tabbed categories on the Jenkins dashboard. By default, Jenkins jobs are created in the All view; this is the tab that you see when you go to the Jenkins dashboard
While demonstrating different CLI commands in this chapter, placeholders use ${}, which should be replaced with actual values.
To create a new job through CLI, you need to specify its specifications using an .XML file, which would be taken as a template for the new job.
You get an error here because Jenkins considered this command coming from an anonymous user, as you have not provided authentication yet. Anonymous users are not authorized to create jobs according to the security configurations of the Jenkins server. Now let's see how to provide the authentication information of a user who is authorized to create a job in this CLI.
Authenticating Users Using Basic Authentication (Username-Password/API Token)
When you perform any task using the Jenkins CLI, you need to provide authentication information to perform that task using the –auth argument. You can authenticate users using basic authentication as well as SSH authentication. Let’s see first how to send Basic Authentication data using the –auth command-line argument. In basic authentication, you have to send a username-password or a username-API token. Sending an API token is the preferred and more secure option.
Log in using the authorized user’s credentials in the Login window. Once you are logged in, you can go to the page to create an API token.
I logged in using my Jenkins administrator credentials.
Click the User Name shown in the top-right corner of the dashboard page.
Click the Configure link to go to the next page, where you can configure API token for the user.
Click the Add New Token button inside the API Token section to generate a new token.
Enter a name in the field and click the Generate button.
Copy the generated token using the Copy This Token button and paste it in a file to preserve it for future use. Click the Save button.
Run the command at the command prompt. Then go to your Jenkins Dashboard page and refresh it. You can see that new job with the name CLIJob1 was created.
Let’s go inside CLIJob1 to see the build step having the Execute Batch command step with the echo Hi, which you also have in the Demo job.
If the template XML file has any syntax issues, the create-job CLI command returns this error: cannot access the file because it is being used by another process. This is quite misleading and not related to the cause of the problem.
If a job with the same name already exists, the create-job command gives the Job Already Exists error.
Authenticating Users Through SSH While Using CLI Commands
You have already seen how to authenticate users using the username-APIToken. Now you'll see how to authenticate Jenkins users using the SSH authentication technique. You are familiar with SSH authentication, which was discussed in previous chapters of this book. The SSH authentication you need is a private key-public key pair.
- 1.
Click the username shown on top-right side of the Dashboard page and click the Configure link.
- 2.
Scroll down the page to find the SSH Public Keys section. Paste the public key you generated into the SSH Public Keys field.
- 3.
Click the Save button.
Configuring an SSH Server in Jenkins
To access Jenkins using SSH authentication, you need to configure the SSH Server in Jenkins. First choose the Manage Jenkins➤Configure Global Security menu, which will take you to the Configure Global Security page.
Scroll down the page to find the SSH Server section near the end.
You need to set a port for the SSH connection. You have two options—Fixed and Random. If you select the Random radio control, the Jenkins server will select a random port to accept SSH connections. If we have a Firewall set up on the machine and need to allow incoming connections made on a specific port, then setting up an inbound rule for the random port will be difficult. If you select the Fixed radio button, you can use the port number of your choice. Jenkins will accept SSH connections on a given port. As the port is fixed, it would be easy to set up an inbound rule in a firewall. I selected the Fixed radio button and set it to 9090. Click the Save button.
Configuring an Inbound Rule in a Firewall
- 1.
Go to the Windows Defender Firewall with Advanced Security menu option from the Windows start menu.
- 2.
Click the Inbound Rules option on left side.
- 3.
Click the New Rule link on the right side, which will open the Rule Type window.
- 4.
Select the Port radio button.
- 5.
Click the Next button.
- 6.
Select the Specific Local Ports radio button and enter 9090.
- 7.
Click the Next button, which will open the Action window.
- 8.
Click the Next button to see the Profile window.
- 9.
Click the Next button to see the Name window.
- 10.
Enter a name for the rule and click the Finish button.
How to Build Jobs with the Jenkins CLI Using SSH Authentication
This section explains how to build a Jenkins job using the Jenkins CLI command build.
-c: If you pass this option to the build command it checks if there are any changes on the SCM configured in the job and triggers the build only if there are changes.
-f: If you pass this option to the build command, it returns the exit code based on the outcome of the build. If the build is successful, it returns an exit code of 0.
-p: Using this option, you can pass parameters to a build in the Key=Value format.
-s: If you pass this option, then the build command will wait until the build completes/gets interrupted. If you do not set this option, the build command will trigger the build but will not wait until its completion.
-v: This option will print the console output of the build.
-w: This option will wait until the start of the command.
Using an SSH client like OpenSSH/Putty
Using Jenkins-cli.jar
Using the OpenSSH Client to Run Jenkins CLI Commands
Let’s use the OpenSSH client to trigger a build using Jenkins CLI build command.
9090 is a port we configured under the SSH Server section in the Jenkins settings.
Pranodayd is a Jenkins user we are authenticating. D:SSHKeyJenkinsCLI is a file with the private key.
Go to the Jenkins dashboard page. You will see that the build for the ReleaseCalculatorAPI job was triggered.
Go to the Jenkins Dashboard page and note that this time the build is not triggered, as we sent the –c option, which checks for changes in the SCM. Since there are no changes in the Git repository, the build is not triggered.
I changed version to 10.0 in pom.xml of the CalculatorAPI project and pushed this change to the Gitlab repository. Then I executed the same Jenkins CLI build command.
You can observe on the Jenkins dashboard that this time, the build was triggered and the console log of the build command was listed because you used the –v option.
Using the jenkins-cli.jar Client to Run Jenkins CLI Commands with SSH
You are already familiar with Jenkins-cli.jar, which you used to run Jenkins CLI commands using the HTTP connection mode. The previous section covered the SSH connection mode and you saw how the SSH client called OpenSSH to run the Jenkins CLI commands. This section explains how to use Jenkins-cli.jar to run Jenkins CLI commands using SSH authentication (SSH Connection mode).
If you are starting the Jenkins server on an IP address (i.e. non-default), then you need to start the Jenkins server with an argument named org.jenkinsci.main.modules.sshd.SSHD.hostName, which will include the IP address of the Jenkins machine as its value.
There should not be whitespace between - and D and -D and org.jenkinsci.main.modules.sshd.SSHD.hostName.
A screenshot of a notepad page in which, dash Dorg dot jenkins c i dot main dot modules dot S S H D dot hostname equals 192.168.43.10, is highlighted and boxed.
The Dorg.jenkinsci.main.modules.sshd.SSHD.hostName in Jenkins.xml
Note that when you are using SSH connection mode, you need to specify -ssh in the command. If you are using -ssh then you must send the user ID with the -user option. By default, jenkins-cli.jar connects to the host and port that the Jenkins server is running on to get the SSH connection. But if you have set up a different port for SSH in the Jenkins server configuration (refer to previous sections of this chapter to learn how to set the SSHD port), as we set it to 9090, you need to specify the -p option in the command.
How to Export All Jobs
Batch Code to Export all Jenkins Jobs
How to Import All Jobs
Batch Code to Import All Jenkins Jobs
The batch code defines the variable JenkinsCLIJarLocation as having the location of Jenkins-cli.jar. It defines the variable JenkinsURL as having the Jenkins URL of the new machine
It defines the variable JobsExportLocation as having the path of the folder in which you exported the job XML files.
The following line runs the Jenkins CLI command create-job${JOB_NAME} < ${CONFIGURATIONFILE} in a loop.
Summary
This chapter explained how to interact with Jenkins server using its CLI (command-line interface) and how to use the Jenkins-cli.jar to interact with the Jenkins server by connecting using HTTP URL and SSH authentication. You also learned, with the help of code snippets, how to perform regular tasks like exporting Jenkins jobs using the Jenkins CLI.