jenkins用户手册-13-CLI-命令

通用命令

jenkins有一系列CLI内置命令，这些命令在每一个jenkins环境中都可见，例如 build 或者 list-jobs.插件也可能提供CLI命令；为了确定jenkins环境给定的全部的可用命令，执行cli  help 命令。

% ssh -l kohsuke -p 53801 localhost help

下面的命令列表不是详尽的，但是是jenkinsCLI 使用的有益的起点。

build

最通用和的cli 命令是build，它允许用户触发任何有权限的任务或者通道（pipeline）

最基本的使用是简单的触发任何或者通道和退出，但是作为附件选项，用户也可以传递参数，选举 SCM，或者甚至跟随触发构建或者运行通道的控制台输出。

% 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 命令，它检索特定的构建或通道运行的控制台输出。当没有提供构建数字，console命令将会输出最后构建的控制台输出。

%ssh -l kohsuke -p 53801 localhost help 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 命令对列举当前用户的授权和可用权限是有用的。当因为缺少特定权限而导致的调试找不到命令是有益的。

% 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属主的 /jnlpJars/jenkins-cli.jar
路径直接下载，有效的下载路径：
https://JENKINS_URL/jnlpJars/jenkins-cli.jar
虽然一个cli的jar 文件可以用来针对不同版本的jenkins，但是使用中可能出现兼容性问题，请从jenkins
属主重新下载最新的jar文件。

使用客户端

通用的引入客户端的语法如下：

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

JENKINS_URL 可以是通过环境变量获取指定。其他通用选项的摘要可以通过运行客户机来显示，而不需要任何参数。

客户端连接模式

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

HTTP连接模式

这个是2.54和2.46.2版本默认的模式，但是你也可以通过
-http 显示指定。

（实际上，密码也是可以接受的，不过这个方式不推荐）

你也可以在参数面前加@符号来从文件中加载相同的内容：

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

通常来说，基于http的cli 连接，不需要特殊的系统配置。如果你用在https反向代理的后面运行jenkins，保证它没有缓存请求和返回体。

注：2.54以及最新版本的 jenkins，
https连接模式在apache的http反向代理服务下使用 mod_proxy不能正常工作。

变通方法包括使用不同的反向代理，例如 nginx或者haproxy。或者可能的话使用ssh连接模式。查看 https://issues.jenkins-ci.org/browse/JENKINS-47279

SSH 连接模式

身份认证是通过SSH 密钥对。你不惜选择jenkins用户id如下：

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

这种模式，客户端本质上像个本机ssh命令行。

默认情况下客户端将会尝试连接jenkins_url所表示主机的ssh端口。如果jenkins使用http反向代理模式，这通常不会工作，所以使用系统参数 - Dorg.jenkinsci.main.modules.sshd.SSHD.hostName=ACTUALHOST
参数运行jenkins来定义一个SSH末端的的主机或者ip地址。

远程连接模式

这个模式只被2.54/2.46.2 之前版本的jenkins服务上下载的客户端支持（在引入-remoting 选项之前）。为了安全和运行效率被弃用。这就是说，某些命令或者命令模式只可以运行在远程模式下，通常是因为命令功能包括在客户端机器上运行服务器提供的代码。

2.54及其更新版本和2.46.2及其更新版本的服务端安装版本这个模式是禁用的。如果你必须使用它，也能接受所带来的风险，可以通过Configure Global Security
来开启。

身份验证最好是通过SSH 秘钥对。登录命令 和 --username/--password 命令（注：不是global）选项也是可以的。这是不建议使用的，因为它们不能喝无密码模式的安全策略一起工作，特定的命令参数可能解析不正确；由于无法使用非基于密码的安全领域，因此这些命令是无效的，如果匿名用户缺乏整体或工作读访问权限，并且在脚本中保存人工选择的密码以供使用，那么某些命令参数将无法得到适当的解析。

注意这种模式有两种传输协议可用：基于HTTP或者基于专用的TCP socket。如果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)

No X-Jenkins-CLI2-Port

转到jenkins管理>全局安全配置 在 JNLP 代理的TCP 端口（TCP port for JNLP agents）下 选择修复(FIXED）或者随机（Random）

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

服务器秘钥校验不通过

你可能得到下面的错误，发现日志入口 与 秘钥不匹配相关

org.apache.sshd.common.SshException: Server key did not validate
at org.apache.sshd.client.session.AbstractClientSession.checkKeys(AbstractClientSession.java:523)
at org.apache.sshd.common.session.helpers.AbstractSession.handleKexMessage(AbstractSession.java:616)
...

这意味着您的SSH配置不承认服务器提供的公钥。

许三多修路