Why would you want to do this?
When I started working on new Jenkins configuration with my colleagues, high on our list of priorities was having reproducible configuration for our Jenkins.
Previously we maintained everything by hand, mostly through the web-based configuration, saved the resulting xmls, and hoped, that if something bad happens, we would be able to restore xml on new Jenkins instance and fix any occurring problems manually.
As we realized later, Jenkins is surprisingly configurable through it's embedded Groovy console. That let us to our plan, where we would write Groovy scripts for configuring various aspects of Jenkins and then tie all of them together with an overarching configuration shell-script.
For this to work, we needed to enable remoting over CLI. This guide will show you how.
Should you want to do this?
If you ever tried to do this before, you might have noticed the warnings, that enabling remoting leads to security vulnerability. You are practically giving access to all of the Jenkins internals to anybody with your key/password and you will be greeted with
"Allowing Jenkins CLI to work in -remoting mode is considered dangerous and usually unnecessary. You are advised to disable this mode."
and big blue button to disable remoting every time you go to "Manage Jenkins" through the web-console.
So, before you bring this into production maybe double-check if there is better way. Jenkins supports access over ssh protocol as well, even though in more limited fashion. Unfortunately, I haven't been able to find a way to distinguish the Jenkins CLI commands that would require remoting and those that would be fine with going through ssh/http.
In future I should look into the alternatives of directly running Groovy scripts.
For now, we really liked the flexibility that remoting gives us so we went all in.
How would you do this?
This is a good place to link the official documentation. Briefly, it could be summarized in these steps:
- add your ssh public key to your account
- enable TCP port for JNLP agents
- enable remoting for CLI
- download the client and run it with Java
After you are done with these four steps you should be able to run all of the CLI commands against your Jenkins.
Add your ssh public key to your account
In you account settings, found at https://$JENKINS_URL/user/$USERNAME/configure you should set your ssh public key.
If you are not familiar with setting up ssh keys, or you would like to generate new one, but keep forgetting how did you do that last time (as happens to me roughly once a month), you can consult a great guide on Github that explains the ssh generation step-by-step.
Enable TCP port for JNLP agents
The preferred option for connecting for CLI is JNLP. In theory, if this isn't enabled, the CLI binary should fall back to http. In practice, for certain commands, such as the groovy command we wanted to be using, you'd receive error about JNLP not being available.
To enable it, go to Manage Jenkins > Configure Global Security and choose "Fixed" or "Random" under TCP port for JNLP agents.
I would advise to set a specific port, so that you can enable the port in your firewall.
Enable remoting for CLI
Before you can use groovy scripts you need to enable remoting over CLI by checking the "Enable CLI over Remoting" in Manage Jenkins > Configure Global Security. As I mentioned, Jenkins will advise you against this, unfortunately, to take advantage of the groovy scripting through Jenkins CLI, this really needs to be enabled.
Download the cli client and run it
You can find the download link directly in your Jenkins instance, through Manage Jenkins > Jenkins CLI, you should even be able to download it directly from https://$JENKINS_URL/jnlpJars/jenkins-cli.jar. To execute it, you will need java runtime present.
To test out the setup, lets use the example you'd find if you wanted to try groovy-scripting from the web-console.
The example there could be translated to a file plugin_list.groovy like this:
You should now be able to execute the file by running:
java -jar jenkins-cli.jar -remoting -s https://$JENKINS_URL groovy plugin_list.groovy
and see something along the lines:
[Plugin:ssh-credentials, Plugin:workflow-job, Plugin:pipeline-github-lib, Plugin:workflow-basic-steps, Plugin:ws-cleanup, Plugin:pipeline-rest-api, Plugin:pipeline-model-api, Plugin:handlebars, Plugin:ace-editor]
To conclude
Now you have unlocked probably most versatile way to configure Jenkins. As they say, with great power comes great responsibility (alongside possible security vulnerabilities), but we really like the power! Most of the scripts I will be describing in other posts utilize groovy-scripts for configuration in one way or other, so unless I find a better way to do this sort of configuration, cli over remoting and groovy scripts are there to stay in our Jenkins configuration.
If you liked this, and want to ask anything, (or didn't and want to tell me how to do something better), feel free to write me an email to adam at asaleh.net!