必威国际有限公司Jenkins Cli.

必威国际有限公司Jenkins有一个内置的命令行界面,允许用户和管理员从脚本或shell环境访问Jenkins。这可以方便地为例程任务、批量更新、故障排除等编写脚本。

可以通过SSH或Jenkins CLI客户端访问命令行界面必威国际有限公司. jar用jenkins分发的文件。必威国际有限公司

本文件假定Jenkins 2.54或更新。必威国际有限公司CLI客户端的旧版本被认为是不安全的并且不应使用。

当使用服务器和客户端2.217或更新版本时,WebSocket支持是可用的。

通过SSH命令行登录

在新的Jenkin必威国际有限公司s安装中,SSH服务默认是禁用的。管理员可以选择设置一个特定的端口,或者让Jenkins在必威国际有限公司配置全球安全页。为了确定随机分配的SSH端口,检查jenkins URL上返回的标头,例如:必威国际有限公司

%curl -lv https:// 必威国际有限公司jenkins_url / login 2>&1 |grep -i'x-ssh-endpoint'

使用随机SSH端口(53801在本例中),并且身份验证配置了,任何现代SSH客户端都可以安全地执行CLI命令。

身份验证

无论使用Jenkins控制器的用于身份验证的用户必须具有必威国际有限公司总体/读允许以便使用权CLI。根据所执行的命令,用户可能需要额外的权限。

SSH方式下的认证依赖于基于SSH的公钥/私钥认证。要为适当的用户添加SSH公钥,导航到必威国际有限公司JENKINS_URL /我/配置并将SSH公钥粘贴到适当的文本区域。

为用户添加SSH公钥

常见的命令

必威国际有限公司Jenkins有许多内置的CLI命令,可以在每个Jenkins环境中找到,例如构建列表工作.插件还可以提供CLI命令;为了确定给定的Jenkins环境中可用的命令的完整列表,执行CLI必威国际有限公司帮助命令:

% SSH -l kohsuke -p 53801 localhost help

下面的命令列表并不全面,但对于Jenkins CLI的使用来说,它是一个有用的起点。必威国际有限公司

构建

最常见和最有用的CLI命令之一是构建,这允许用户触发它们具有许可的任何作业或管道。

最基本的调用将简单地触发作业或管道并退出,但使用其他选项,用户还可以通过参数,轮询SCM,甚至遵循触发构建或管道运行的控制台输出。

% ssh -l kohsuke -p 53801 localhost help build java -jar 必威国际有限公司jenkins-cli.jar build JOB [-c] [-f] [-p] [-r N] [-s] [-v] [-w]启动构建,并可选地等待完成。除了一般的脚本使用外,该命令还可以用于从一个作业的构建中调用另一个作业。使用-s选项,该命令根据构建结果更改退出代码(退出代码0表示成功),并且中断该命令将中断作业。使用-f选项,该命令将根据构建结果更改退出代码(退出代码0表示成功),然而,与-s不同的是,中断命令不会中断作业(退出代码125表示命令被中断)。使用-c选项,只有当SCM发生更改时,构建才会运行。JOB:要构建的工作的名称-c:在开始构建之前检查SCM更改,如果没有更改,则不进行构建就退出-f:遵循构建进度。像-s一样,只有中断不会传递到构建中。-p:以key=value格式指定构建参数。-s:等待命令执行完毕/终止。中断被传递到构建中。 -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 %

控制台

同样有用的是控制台命令,它检索指定构建或管道运行的控制台输出。如果没有提供构建号,则控制台命令将输出最后一个完成的构建的控制台输出。

% ssh - l kohsuke - p 53801 localhost帮助控制台java jar jenkins-必威国际有限公司cli.jar控制台工作[制造][f] [N N]产生特定的构建到stdout的控制台输出,就好像你在做“猫build.log”工作:工作名称构建:构建数字或永久链接指向构建。默认为最后一个构建-f:如果构建正在进行中,待在附近并在它出现时附加控制台输出,如'tail -f' -n N:显示最后N行% ssh - l kohsuke - p 53801主机控制台build-all-software从命令行开始kohsuke工作区中的建筑/ tmp / jenkins / workspace / build-all-software [build-all-software]美元/bin/必威国际有限公司sh xe / tmp / hudson1100603797526301795.sh +回声hello world是的完成:成功%

我是谁

我是谁命令有助于列出当前用户可用的凭证和权限。这在调试由于缺乏某些权限而导致CLI命令不存在时非常有用。

% ssh -l kohsuke -p 53801 localhost help who-am-i java -jar 必威国际有限公司jenkins-cli.jar who-am-i报告您的凭证和权限。% ssh -l kohsuke -p 53801 localhost who-am-i Authenticated as: kohsuke Authorities: Authenticated %

使用CLI客户端

虽然基于ssh的CLI速度很快,并能满足大多数需求,但在某些情况下,使用Jenkins分发的CLI客户机可能更适合。必威国际有限公司例如,CLI客户端的默认传输是HTTP,这意味着不需要在防火墙中打开其他端口。

比较SSH和CLI客户端

SSH和Jenkins -必威国际有限公司cli.jar都提供对一组命令的访问,使您可以从命令行与Jenkins进行交互,但它们有一些不同:

  • 必威国际有限公司Jenkins SSH不需要客户端上的任何定制jar文件,这使得从各种来源访问Jenkins变得更容易

  • SSH客户机被构建为一个通用工具,用于多种目的。它没有提供一种简单的方法来完成Jenkins环境中常见的、特定的基本工作。必威国际有限公司使用必威国际有限公司jenkins-cli.jar而不是SSH客户端可以提高生产力和改善开发体验

下载客户端

CLI客户端可以通过URL直接从Jenkins控制器下载必威国际有限公司/ jnlpJars必威国际有限公司 jenkins-cli.jar实际上必威国际有限公司JENKINS_URL / jnlpJars / jenkins-cli.jar

而一个CLI. jar可以用于不同版本的Jenkins,如果在使用过程中出现兼容性问题,请重新下载最新版本必威国际有限公司. jar文件从Jenkins控制器。必威国际有限公司

使用客户端

调用客户端的通用语法如下:

java -jar 必威国际有限公司jenkins-cli.jar [-s JENKINS_URL] [global options…]命令[命令选项…]][论点……]

必威国际有限公司JENKINS_URL可以通过环境变量指定J必威国际有限公司ENKINS_URL美元.通过运行完全不带参数的客户机,可以显示其他通用选项的摘要。

客户端连接模式

客户端可以使用三种基本模式,可通过全局选项选择:httpwebsocket,ssh

HTTP连接模式

这是默认模式,尽管您可以通过http选项明确为清晰。

身份验证最好使用身份验证选项,它需要一个用户名:apitoken论点。获取API令牌/我/配置

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命令……

出于安全原因,建议使用文件加载身份验证凭据。

另一种认证方法是以与类似方式配置环境变量J必威国际有限公司ENKINS_URL美元使用。这用户名可以通过环境变量指定J必威国际有限公司ENKINS_USER_ID美元apitoken可以通过变量指定J必威国际有限公司ENKINS_API_TOKEN美元.必须同时设置这两个变量。

export 必威国际有限公司JENKINS_USER_ID=kohsuke export JENKINS_API_TOKEN=abc1234ffe4a java -jar jenkins-cli.jar [-s JENKINS_URL] command…

在配置了这些环境变量的情况下,仍然可以使用不同的凭据覆盖身份验证方法身份验证选项,它优先于它们。

通常,启用基于http的CLI连接不需要进行特殊的系统配置。如果您在HTTP(S)反向代理后面运行必威国际有限公司Jenkins,请确保它不缓冲请求或响应体。

在使用某些反向代理时,已知该模式无法可靠地或根本完全起作用。更喜欢WebSocket模式。

WebSocket连接模式

在Je必威国际有限公司nkins 2.217及以上版本中websocket模式可以作为替代http.优点是使用了更标准的传输,避免了许多反向代理的问题或需要特殊的代理配置。

SSH连接模式

身份验证通过SSH密钥对进行。您还必须选择Jenkins用户ID:必威国际有限公司

java -jar 必威国际有限公司jenkins-cli.jar [-s jenkins_url] -ssh -user kohsuke命令...

在这种模式下,客户机的行为本质上类似于本机s命令。

默认情况下,客户端将尝试在同一主机上连接到SSH端口必威国际有限公司JENKINS_URL.如果J必威国际有限公司enkins在HTTP反向代理后面,这通常不会工作,所以使用系统属性运行Jenkins-Dorg.必威国际有限公司jenkinsci.main.modules.sshd.SSHD.hostName = ACTUALHOST为SSH端点定义主机名或IP地址。

CLI客户端常见问题

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

服务器密钥未验证

您可能会收到以下错误,并在此处查找一个日志条目。不匹配的钥匙

org.apache.sshd.common.sshexception:服务器密钥未在org.apache.sshd.client.session.abstractclients.CheckKeys(AstraptsClients.java:523)验证.Checkkeys.sshd.commmon.session.helpers.abstractsession.HandlekexMessage(AbstractSession.java:616)......

这意味着您的SSH配置无法识别服务器呈现的公钥。当您在DEV模式下运行Jenkins时,通常情况日常是这种情况,并必威国际有限公司且在相同的SSH端口下运行了多个应用程序随时间运行。

在开发环境中,访问您的〜/ .ssh /已知_hosts(或在C: /用户/ < your_name > / . ssh / known_hosts对于Windows),然后删除与当前SSH端口对应的行(例如(localhost): 3485)。在生产背景下,如果最近服务器的公钥更改,请检查Jenkins管理员。必威国际有限公司如果是这样,请求管理员执行上述步骤。

UsernameNotFoundException

如果你的客户端显示的堆栈跟踪如下:

org.acegisecurity.userdetails.UsernameNotFoundException: < name_you_used >…

这意味着您的SSH密钥是根据存储的用户识别和验证的,但是用户名对于您的应用程序当前使用的安全领域是无效的。当您最初使用Jenkins数据库、配置用户,然后切换到另一个安全领域(如LDAP等必威国际有限公司),其中定义的用户还不存在时,可能会发生这种情况。

要解决问题,请确保您的用户存在于配置的安全领域。

故障排除日志

要获取有关身份验证过程的更多信息:

  1. 进入管理詹金斯必威国际有限公司>系统日志>增加新的计程仪

  2. 输入您想要的任何名称,然后单击好吧

  3. 点击添加

  4. 类型org.必威国际有限公司jenkinsci.main.modules.sshd.PublicKeyAuthenticatorImpl(或类型PublicKeyAuth然后选择全名)

  5. 设置级别所有

  6. 重复前三个步骤hudson.model.User

  7. 点击保存

当您尝试进行身份验证时,您可以刷新页面并查看内部发生了什么。



这个页面有用吗?

请通过这个提交你对这个页面的反馈快速形成

或者,如果您不希望完成快速表单,您可以简单地指出,如果您觉得这个页面有帮助?


看到现有的反馈在这里