Jenkins CLI

Jenkins有一个内置的命令行界面，允许用户和管理员从脚本或shell环境访问Jenkins。这对于日常任务的脚本编写，批量更新，故障排除等都是很方​​便的。

命令行界面可以通过SSH或Jenkins CLI客户端进行访问，这是Jenkins .jar发布的一个文件。

不建议使用与Jenkins 2.53及更早版本Jenkins 2.5.3及更早版本配合使用的CLI客户端，因为安全原因：虽然目前还存在未知的漏洞，但是有几个已经被报告和修补过，而Jenkins Remoting协议使用本身就容易受到远程代码执行错误的影响，甚至是“预认证”漏洞（由能够物理访问Jenkins网络的匿名用户）。

Jenkins 2.54和更新版本的Jenkins LTS 2.46.2和更新版本的客户端在其默认（-http）或-ssh模式下被认为是安全的，正如使用标准ssh命令一样

通过SSH使用CLI

在新的Jenkins安装中，默认情况下禁用SSH服务。管理员可以选择设置特定端口，或者请求Jenkins在“ 配置全局安全性”页面中选择一个随机端口。为了确定随机分配的SSH端口，请检查Jenkins URL上返回的标头，例如：

% curl -Lv https://JENKINS_URL/login 2>&1 | grep 'X-SSH-Endpoint'
< X-SSH-Endpoint: localhost:53801
%

使用随机SSH端口（53801在本示例中）和身份验证 配置，任何现代SSH客户端都可以安全地执行CLI命令。

认证

用于与Jenkins主机进行身份验证的用户必须具有访问 CLI 的 Overall/Read权限。根据执行的命令，用户可能需要额外的权限。

认证依赖于基于SSH的公钥/私钥认证。要为适当的用户添加SSH公钥，请导航 https://JENKINS_URL/user/USERNAME/configure并将SSH公钥粘贴到相应的文本区域中。

共同命令

Jenkins有许多内置的CLI命令，可以在每个Jenkins环境中找到，例如build或list-jobs。插件还可以提供CLI命令; 为了确定给定Jenkins环境中可用的命令的完整列表，请执行CLI help命令：

% ssh -l kohsuke -p 53801 localhost help

以下命令列表并不全面，但它是Jenkins CLI使用的有用起点。

建立

CLI命令中最常用和最有用的命令之一是build允许用户触发他们有权限的任何作业或pipeline。

最基本的调用将简单地触发作业或pipeline并退出，但是使用附加选项，用户也可以传递参数，轮询SCM，甚至跟随触发构建或pipeline运行的控制台输出。

% ssh -l kohsuke -p 53801 localhost help build

java -jar jenkins-cli.jar build JOB [-c] [-f] [-p] [-r N] [-s] [-v] [-w]
Starts a build, and optionally waits for a completion.  Aside from general
scripting use, this command can be used to invoke another job from within a
build of one job.  With the -s option, this command changes the exit code based
on the outcome of the build (exit code 0 indicates a success) and interrupting
the command will interrupt the job.  With the -f option, this command changes
the exit code based on the outcome of the build (exit code 0 indicates a
success) however, unlike -s, interrupting the command will not interrupt the
job (exit code 125 indicates the command was interrupted).  With the -c option,
a build will only run if there has been an SCM change.
 JOB : Name of the job to build
 -c  : Check for SCM changes before starting the build, and if there's no
       change, exit without doing a build
 -f  : Follow the build progress. Like -s only interrupts are not passed
       through to the build.
 -p  : Specify the build parameters in the key=value format.
 -s  : Wait until the completion/abortion of the command. Interrupts are passed
       through to the build.
 -v  : Prints out the console output of the build. Use with -s
 -w  : Wait until the start of the command
% ssh -l kohsuke -p 53801 localhost build build-all-software -f -v
Started build-all-software #1
Started from command line by admin
Building in workspace /tmp/jenkins/workspace/build-all-software
[build-all-software] $ /bin/sh -xe /tmp/hudson1100603797526301795.sh
+ echo hello world
hello world
Finished: SUCCESS
Completed build-all-software #1 : SUCCESS
%

console

同样有用的是console命令，它检索指定生成或pipeline运行的控制台输出。当没有提供编号时，该 console命令将输出最后完成的版本的控制台输出。

% ssh -l kohsuke -p 53801 localhost help console

java -jar jenkins-cli.jar console JOB [BUILD] [-f] [-n N]
Produces the console output of a specific build to stdout, as if you are doing 'cat build.log'
 JOB   : Name of the job
 BUILD : Build number or permalink to point to the build. Defaults to the last
         build
 -f    : If the build is in progress, stay around and append console output as
         it comes, like 'tail -f'
 -n N  : Display the last N lines
% ssh -l kohsuke -p 53801 localhost console build-all-software
Started from command line by kohsuke
Building in workspace /tmp/jenkins/workspace/build-all-software
[build-all-software] $ /bin/sh -xe /tmp/hudson1100603797526301795.sh
+ echo hello world
yes
Finished: SUCCESS
%

who-am-i

该who-am-i命令有助于列出用户可用的当前用户的凭据和权限。当调试缺少CLI命令时，由于缺少某些权限，这将非常有用。

% ssh -l kohsuke -p 53801 localhost help who-am-i

java -jar jenkins-cli.jar who-am-i
Reports your credential and permissions.
% ssh -l kohsuke -p 53801 localhost who-am-i
Authenticated as: kohsuke
Authorities:
  authenticated
%

使用CLI客户端

尽管基于SSH的CLI速度快，涵盖了大部分需求，但可能会出现与Jenkins分发的CLI客户端更适合的情况。例如，CLI客户端的默认传输是HTTP，这意味着在防火墙中不需要打开额外的端口供其使用。

下载客户端

该CLI客户端可以直接从Jenkins管理在URL下载 /jnlpJars/jenkins-cli.jar，在效果 https://JENKINS_URL/jnlpJars/jenkins-cli.jar

虽然CLI .jar可以针对不同版本的Jenkins使用，但如果在使用过程中出现任何兼容性问题，请.jar 从Jenkins管理重新下载最新的文件。

使用客户端

调用客户端的一般语法如下：

java -jar jenkins-cli.jar [-s JENKINS_URL] [global options...] command [command options...] [arguments...]

客户端连接模式

有三种基本模式，其中可以使用本2.54+ / 2.46.2+客户端，通过全局选项可选择的： -http; -ssh; 和-remoting。

HTTP连接模式

这是2.54和2.46.2的默认模式，尽管-http为了清楚起见，您可以明确地传递选项。

认证最好有一个-auth选项，它需要一个username:apitoken参数。获取您的API令牌/me/configure：

java -jar jenkins-cli.jar [-s JENKINS_URL] -auth kohsuke:abc1234ffe4a command ...

（也接受实际的密码，但不鼓励）。

您还可以在参数之前@从文件加载相同的内容：

java -jar jenkins-cli.jar [-s JENKINS_URL] -auth @/home/kohsuke/.jenkins-cli command ...

通常，不需要特殊的系统配置来启用基于HTTP的CLI连接。如果您在HTTP（S）反向代理之后运行Jenkins，请确保它不缓冲请求或响应体。

SSH连接模式

验证是通过SSH密钥对。您还必须选择Jenkins用户ID：

java -jar jenkins-cli.jar [-s JENKINS_URL] -ssh -user kohsuke command ...

在这种模式下，客户端的行为基本上就像一个本机ssh命令。

默认情况下，客户端将尝试连接到同一主机上的SSH端口JENKINS_URL。如果Jenkins位于HTTP反向代理之后，这通常不起作用，因此运行Jenkins与系统属性-Dorg.jenkinsci.main.modules.sshd.SSHD.hostName=ACTUALHOST 来定义SSH端点的主机名或IP地址。

远程连接模式

这是从2.54 / pre-2.46.2之前的Jenkins服务器（在引入该-remoting选项之前）下载的客户端支持的唯一模式。由于安全性和性能原因，它的使用已被弃用。也就是说，某些命令或命令模式只能在Remoting模式下运行，这通常是因为命令功能涉及在客户机上运行服务器提供的代码。

在2.54+和2.46.2的新安装中，服务器端禁用此模式。如果您必须使用它并接受风险，则可能会在配置全局安全性中启用。

验证最好通过SSH密钥对。一个login命令和--username/ --password命令（注意：不是全球性）选项也可用; 这些是不鼓励的，因为它们无法使用基于非密码的安全领域，如果匿名用户缺少整体或作业读取访问权限，某些命令参数将无法正确解析，并且将保存用于脚本的人为选择的密码视为不安全。

请注意，有两种可用于此模式的传输：通过HTTP或专用TCP套接字。如果TCP端口启用并且可以工作，客户端将使用此传输。如果TCP端口被禁用，或者这样的端口被通告但不接受连接（例如因为您使用带有防火墙的HTTP反向代理），客户端将自动回退到效率较低的HTTP传输。

基于远程客户端的常见问题

运行CLI客户端时可能会遇到一些常见的问题。

操作超时

如果您在服务器上使用防火墙，请检查是否打开HTTP端口或TCP端口。您可以在Jenkins配置中配置其值。默认设置为使用随机端口。

% java -jar jenkins-cli.jar -s JENKINS_URL help
Exception in thread "main" java.net.ConnectException: Operation timed out
    at java.net.PlainSocketImpl.socketConnect(Native Method)
    at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:351)
    at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:213)
    at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:200)
    at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:432)
    at java.net.Socket.connect(Socket.java:529)
    at java.net.Socket.connect(Socket.java:478)
    at java.net.Socket.<init>(Socket.java:375)
    at java.net.Socket.<init>(Socket.java:189)
    at hudson.cli.CLI.<init>(CLI.java:97)
    at hudson.cli.CLI.<init>(CLI.java:82)
    at hudson.cli.CLI._main(CLI.java:250)
    at hudson.cli.CLI.main(CLI.java:199)

没有X-Jenkins-CLI2端口

转到管理Jenkins > 配置全局安全性，并在JNLP代理的TCP端口下选择“固定”或“随机” 。

java.io.IOException: No X-Jenkins-CLI2-Port among [X-Jenkins, null, Server, X-Content-Type-Options, Connection,
        X-You-Are-In-Group, X-Hudson, X-Permission-Implied-By, Date, X-Jenkins-Session, X-You-Are-Authenticated-As,
        X-Required-Permission, Set-Cookie, Expires, Content-Length, Content-Type]
    at hudson.cli.CLI.getCliTcpPort(CLI.java:284)
    at hudson.cli.CLI.<init>(CLI.java:128)
    at hudson.cli.CLIConnectionFactory.connect(CLIConnectionFactory.java:72)
    at hudson.cli.CLI._main(CLI.java:473)
    at hudson.cli.CLI.main(CLI.java:384)
    Suppressed: java.io.IOException: Server returned HTTP response code: 403 for URL: http://citest.gce.px/cli
        at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1840)
        at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1441)
        at hudson.cli.FullDuplexHttpStream.<init>(FullDuplexHttpStream.java:78)
        at hudson.cli.CLI.connectViaHttp(CLI.java:152)
        at hudson.cli.CLI.<init>(CLI.java:132)
        ... 3 more