Windows: missing documentation about passing `JENKINS_JAVA_OPTS` with mandatory double quotes

dduportal commented 1 year ago

Jenkins and plugins versions report

Environment

```text Jenkins: 2.375.1 OS: Linux - 5.4.0-1095-azure --- ace-editor:1.1 analysis-model-api:10.20.0 ansicolor:1.0.2 ant:481.v7b_09e538fcca antisamy-markup-formatter:155.v795fb_8702324 apache-httpcomponents-client-4-api:4.5.13-138.v4e7d9a_7b_a_e61 authentication-tokens:1.4 aws-credentials:191.vcb_f183ce58b_9 aws-java-sdk:1.12.287-357.vf82d85a_6eefd aws-java-sdk-cloudformation:1.12.287-357.vf82d85a_6eefd aws-java-sdk-codebuild:1.12.287-357.vf82d85a_6eefd aws-java-sdk-ec2:1.12.287-357.vf82d85a_6eefd aws-java-sdk-ecr:1.12.287-357.vf82d85a_6eefd aws-java-sdk-ecs:1.12.287-357.vf82d85a_6eefd aws-java-sdk-efs:1.12.287-357.vf82d85a_6eefd aws-java-sdk-elasticbeanstalk:1.12.287-357.vf82d85a_6eefd aws-java-sdk-iam:1.12.287-357.vf82d85a_6eefd aws-java-sdk-logs:1.12.287-357.vf82d85a_6eefd aws-java-sdk-minimal:1.12.287-357.vf82d85a_6eefd aws-java-sdk-sns:1.12.287-357.vf82d85a_6eefd aws-java-sdk-sqs:1.12.287-357.vf82d85a_6eefd aws-java-sdk-ssm:1.12.287-357.vf82d85a_6eefd azure-container-agents:253.vd2f5cd5c5040 azure-credentials:242.vb_f9c4fa_6b_2b_6 azure-sdk:118.v43f74dd9ca_dc azure-vm-agents:822.v3a18fc3d2de1 basic-branch-build-strategies:71.vc1421f89888e beer:42.v776b_04d96de3 blueocean:1.25.8 blueocean-autofavorite:1.2.5 blueocean-bitbucket-pipeline:1.25.8 blueocean-commons:1.25.8 blueocean-config:1.25.8 blueocean-core-js:1.25.8 blueocean-dashboard:1.25.8 blueocean-display-url:2.4.1 blueocean-events:1.25.8 blueocean-git-pipeline:1.25.8 blueocean-github-pipeline:1.25.8 blueocean-i18n:1.25.8 blueocean-jira:1.25.8 blueocean-jwt:1.25.8 blueocean-personalization:1.25.8 blueocean-pipeline-api-impl:1.25.8 blueocean-pipeline-editor:1.25.8 blueocean-pipeline-scm-api:1.25.8 blueocean-rest:1.25.8 blueocean-rest-impl:1.25.8 blueocean-web:1.25.8 bootstrap4-api:4.6.0-5 bootstrap5-api:5.2.1-3 bouncycastle-api:2.26 branch-api:2.1051.v9985666b_f6cc buildtriggerbadge:251.vdf6ef853f3f5 caffeine-api:2.9.3-65.v6a_47d0f4d1fe checks-api:1.8.0 cloud-stats:254.v47891b_b_5b_6f6 cloudbees-bitbucket-branch-source:791.vb_eea_a_476405b cloudbees-folder:6.800.v71307ca_b_986b code-coverage-api:3.4.0 command-launcher:90.v669d7ccb_7c31 commons-lang3-api:3.12.0-36.vd97de6465d5b_ commons-text-api:1.10.0-27.vb_fa_3896786a_7 conditional-buildstep:1.4.2 config-file-provider:3.11.1 configuration-as-code:1569.vb_72405b_80249 copyartifact:1.48 credentials:1214.v1de940103927 credentials-binding:523.vd859a_4b_122e6 cvs:2.19.1 dark-theme:262.v0202a_4c8fb_6a data-tables-api:1.12.1-4 disable-github-multibranch-status:1.2 display-url-api:2.3.6 docker-commons:1.21 docker-workflow:528.v7c193a_0b_e67c durable-task:503.v57154d18d478 ec2:2.0.4 echarts-api:5.4.0-1 embeddable-build-status:304.vdcf48d6b_d2eb extended-read-permission:3.2 external-monitor-job:203.v683c09d993b_9 favorite:2.4.1 font-awesome-api:6.2.1-1 forensics-api:1.16.0 generic-tool:1.0 git:4.14.1 git-client:3.13.0 git-forensics:1.11.0 github:1.36.0 github-api:1.303-400.v35c2d8258028 github-branch-source:1696.v3a_7603564d04 github-checks:1.0.19 groovy:453.vcdb_a_c5c99890 handlebars:3.0.8 handy-uri-templates-2-api:2.1.8-22.v77d5b_75e6953 htmlpublisher:1.31 http_request:1.16 instance-identity:116.vf8f487400980 ionicons-api:31.v4757b_6987003 jackson2-api:2.14.1-313.v504cdd45c18b jacoco:3.3.2 jakarta-activation-api:2.0.1-2 jakarta-mail-api:2.0.1-2 javadoc:226.v71211feb_e7e9 javax-activation-api:1.2.0-5 javax-mail-api:1.6.2-8 jaxb:2.3.7-1 jdk-tool:63.v62d2fd4b_4793 jenkins-design-language:1.25.8 jersey2-api:2.37-1 jira:3.8 jjwt-api:0.11.5-77.v646c772fddb_0 jnr-posix-api:3.1.16-1 jobConfigHistory:1187.v2a_b_1ca_54d18d jquery:1.12.4-1 jquery-detached:1.2.1 jquery3-api:3.6.1-2 jsch:0.1.55.61.va_e9ee26616e7 junit:1166.va_436e268e972 junit-attachments:101.v82f494a_00e9e junit-realtime-test-reporter:90.v7dc2c937f9a_8 keyboard-shortcuts-plugin:1.4 kubernetes:3734.v562b_b_a_627ea_c kubernetes-client-api:5.12.2-193.v26a_6078f65a_9 kubernetes-credentials:0.9.0 ldap:2.12 lockable-resources:1069.v726298f53f8c mailer:438.v02c7f0a_12fa_4 mapdb-api:1.0.9-28.vf251ce40855d matrix-auth:3.1.5 matrix-project:785.v06b_7f47b_c631 maven-plugin:3.20 metrics:4.2.10-405.v60a_9cc74e923 mina-sshd-api-common:2.9.2-50.va_0e1f42659a_a mina-sshd-api-core:2.9.2-50.va_0e1f42659a_a momentjs:1.1.1 node-iterator-api:49.v58a_8b_35f8363 okhttp-api:4.9.3-108.v0feda04578cf pam-auth:1.10 parallel-test-executor:318.va_e768e2e32e3 parameterized-trigger:2.45 pipeline-build-step:2.18 pipeline-github:2.8-138.d766e30bb08b pipeline-github-lib:38.v445716ea_edda_ pipeline-graph-analysis:195.v5812d95a_a_2f9 pipeline-graph-view:144.vf3924feb_7e35 pipeline-groovy-lib:621.vb_44ce045b_582 pipeline-input-step:466.v6d0a_5df34f81 pipeline-milestone-step:101.vd572fef9d926 pipeline-model-api:2.2118.v31fd5b_9944b_5 pipeline-model-definition:2.2118.v31fd5b_9944b_5 pipeline-model-extensions:2.2118.v31fd5b_9944b_5 pipeline-rest-api:2.28 pipeline-stage-step:296.v5f6908f017a_5 pipeline-stage-tags-metadata:2.2118.v31fd5b_9944b_5 pipeline-stage-view:2.28 plain-credentials:139.ved2b_9cf7587b plugin-util-api:2.19.0 popper-api:1.16.1-3 popper2-api:2.11.6-2 prism-api:1.29.0-1 pubsub-light:1.17 run-condition:1.5 scm-api:621.vda_a_b_055e58f7 script-security:1218.v39ca_7f7ed0a_c snakeyaml-api:1.33-90.v80dcb_3814d35 sse-gateway:1.26 ssh-agent:295.v9ca_a_1c7cc3a_a_ ssh-credentials:305.v8f4381501156 ssh-slaves:2.854.v7fd446b_337c9 sshd:3.270.vb_a_e71e64c287 structs:324.va_f5d6774f3a_d subversion:2.16.0 support-core:1229.v84a_e1b_3a_1d32 theme-manager:1.5 timestamper:1.21 token-macro:321.vd7cc1f2a_52c8 translation:1.16 trilead-api:2.84.v72119de229b_7 variant:59.vf075fe829ccb warnings-ng:9.20.1 windows-azure-storage:380.va3a027b784f4 workflow-aggregator:590.v6a_d052e5a_a_b_5 workflow-api:1200.v8005c684b_a_c6 workflow-basic-steps:994.vd57e3ca_46d24 workflow-cps:3536.vb_8a_6628079d5 workflow-durable-task-step:1217.v38306d8fa_b_5c workflow-job:1254.v3f64639b_11dd workflow-multibranch:716.vc692a_e52371b_ workflow-scm-step:400.v6b_89a_1317c9a_ workflow-step-api:639.v6eca_cd8c04a_a_ workflow-support:839.v35e2736cfd5c ```

What Operating System are you using (both controller, and any agents involved in the problem)?

Controller: Linux (Ubuntu 18.04)
Agent: Windows Server 2019 with agent nanoserver (version 3077.vd69cf116da_6f-3)

Reproduction steps

Create up a permanent inbound agent
Start an interactive container based on the jenkins/inbound-agent:3077.vd69cf116da_6f-3-jdk11-nanoserver image
```
docker run --rm -ti --entrypoint=pwsh jenkins/inbound-agent:3077.vd69cf116da_6f-3-jdk11-nanoserver
```

Define the JENKINS_JAVA_OPTS environment the variable in the current shell:

$env:JENKINS_JAVA_OPTS = '-XX:+PrintCommandLineFlags' # Same as our ACI containers

Execute the agent process by calling the default entrypoint (adapt parameters to your case):

C:/ProgramData/Jenkins/jenkins-agent.ps1 -Url <controller URL> -Secret <redacted> -Name <agent name>

Expected Results

The agent should start and connect to the controller successfully. This is the behavior if you unset the environment variable JENKINS_JAVA_OPTS.

Actual Results

The agent process fails to start with the following error:

Unrecognized VM option ''
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

because the java flag -XX:+PrintCommandLineFlags is interpolated by the script when variable is parsed, resulting in a call like this one: java -XX:

Anything else?

Discovered with https://github.com/jenkins-infra/helpdesk/issues/3274
Caused by https://github.com/jenkinsci/docker-inbound-agent/pull/227

slide commented 1 year ago

As mentioned in the PR, you have to follow Powershell escaping rules for the parameters, the environment variable would need to be "-XX:+PrintCommandLineFlags" with quotes included.

dduportal commented 1 year ago

Thanks for the fast answer @slide ❤️

I'll open a PR here to document the quoting part (instead of rollbacking your PR) does it make sense to you?

slide commented 1 year ago

https://github.com/jenkinsci/docker-inbound-agent/blob/master/jenkins-agent.ps1#L99 this is the comment about the quoting from the PR

slide commented 1 year ago

Please verify the quoting change works 😄

lemeurherve commented 1 year ago

Documented in https://github.com/jenkinsci/docker-inbound-agent/pull/313

jenkinsci / docker-agent