Skip to end of metadata
Go to start of metadata

Background

Cygwin is a Unix emulation library for Windows. It allows source code written for POSIX environment to be compiled with Cygwin stub files into Windows executables. When these Cygwin-enabled libraries run, a DLL gets loaded into these processes that implement all the POSIX APIs on top of Win32 APIs.

Because of the way it works, cygwin's presence does not change the way Java virtual machines work. JVMs that run on Cygwin-enabled Windows continue to behave exactly the same way as JVMs that run on cygwin-less Windows. It will continue to use '\' as the separator, not '/', java.io.File will not suddenly start understanding Unix path, etc. The path translation from the UNIX style to the Windows style happens within Cygwin DLL. Programs that are not compiled against Cygwin will not load Cygwin DLL, and as such they will not go through the path translation.

So when you use Cygwin and mix native Windows programs and Cygwin-compiled programs, you need to be mindful when and where the path conversions happen. For example, when you execute Cygwin-compiled processes (say bash.exe), these programs expect Unix-style paths in their command line. The same applies when we talk to Cygwin-compiled processes over various protocols, such as SFTP.

To make this further confusing, native Windows APIs recognizes '\' as the directory separator, in addition to '/'. Simiarly, Cygwin-emulated POSIX APIs accept Windows paths, in addition to the Unix paths. This helpful "smart" behaviour sometimes makes it difficult for users to understand where the path translation is really happening.

SSH slaves plugin and Cygwin SSHD.

Cygwin comes with OpenSSH server, which works well with SSH slaves plugin. This is one of the recommended way of controlling Windows slaves from Jenkins, if you don't mind the added effort of installing Cygwin and sshd.

When you use SSH launcher to launch a slave on Cygwin-enabled Windows, you should still specify Windows style path as the remote FS root (such as c:\jenkins). This is because the slave JVM that eventually gets launched doesn't receive the Cygwin path translation. If you specify Unix style path (such as /cygdrive/c/jenkins), then Jenkins will end up trying to create both c:\jenkins (when it copies over slave.jar via SFTP) and c:\cygdrive\c\jenkins (when slave JVM actually starts and copy more files.)

If you run Jenkins on behalf of other users, you'll discover that some of your users will not understand when and where the path translation happens, and will inevitably write build scripts that break. You can explain to them what's going on, or you can surrender and use mklink to create a symlink or junction point that maps c:\cygdrive\c\jenkins to c:\jenkins. This will make those broken scripts work happily.

Treating Cygwin slaves like Unix slaves

Sometimes you want to treat Cygwin slaves like real Unix slaves, such as running shell scripts. When you do it, you often see error messages like this:

java.io.IOException: Cannot run program "/bin/bash" (in directory "c:\test\workspace\foo"):
  CreateProcess error=3, The system cannot find the path specified

This is because Jenkins is trying to call Windows API and execute "/bin/bash" without going through Cygwin path translation. Windows interprets /bin/bash as c:\bin\bash.exe, and unless that path exists, it will fail.

In this case, what's needed is to have Jenkins perform the Cygwin path translation without relying on Cygwin DLL. This is what Cygpath Plugin does; it checks if a Windows slave have Cygwin, and if you try to run executable that looks like Unix path name, it'll use Cygwin to translate that into its Windows path before calling Windows API.

Further Reading

Jenkins slaves running on Cygwin-enabled Windows is still susceptible to all the other problems Windows slaves face. See My software builds on my computer but not on Jenkins for the discussion of those, including desktop and network drive access.

4 Comments

  1. Windows Master and Slave Setup across a Firewall using SSH

    This setup seems to work for me after a lot of trial and error:

    For corporate reasons, my Jenkins master is on our Primary domain, and some of the slaves are on a Test domain, which is a different physical network, connected only by a router/firewall. Traffic can go freely from the Primary to the Test domain, but very little traffic can go from the Test to the Primary (I couldn't even use Java WebStart, and I couldn't get the DCOM option to work reliably). I can, however authenticate Primary domain credentials on the Test domain (it isn't necessary to this setup, though; a local user could be used on the target machine).

    • Install OpenSSH (via Cygwin)
      • General References:
      • To ensure that scripts run with elevated permissions, run the SSHd service as the same user who will be logging in (ex. PRIMARY\builder)
        1. Log in to the target machine as PRIMARY\builder
        2. Install Cygwin, with the OpenSSH package
        3. Start a Cygwin prompt with elevated permissions
        4. Run ssh-host-config
          1. Should Privilege Separation be used? = yes
          2. create a new local account 'sshd'? = yes
          3. Do you want to install sshd as a service? = yes
          4. Enter the value of CYGWIN for the daemon [] = ntsec     (sets the %CYGWIN% environment variable)
          5. (When creating the cyg_server user) Do you want to use a different name? = yes
          6. Enter the user name = builder
          7. (The rest of the prompts are straightforward)
        5. (Still in the Cygwin console) Make a passwd file by running: mkpasswd -c >> /etc/passwd
        6. Make a group file by running: mkgroup -c > /etc/group
        7. Assign some special permissions required for SSH:
          1. editrights.exe -a SeAssignPrimaryTokenPrivilege -u builder
          2. editrights.exe -a SeCreateTokenPrivilege -u builder
          3. editrights.exe -a SeTcbPrivilege -u builder
          4. editrights.exe -a SeServiceLogonRight -u builder
        8. exit the cygwin prompt
        9. (question) May need to set the "Interact with desktop" flag on the service in Services.msc?
        10. Start the Cygwin SSHD service
      • Open a FireWall exception for port 22
      • Connect to the machine from the Jenkins master, using PuTTY to establish connectivity and cache the SSH key
    • Setup the node on Jenkins
      • Choose the Launch slave agents on Unix machines via SSH option
      • Specify credentials for PRIMARY\builder
      • Add the TEMP environment variable in the Jenkins slave setup. This variable does not get automatically inherited from Windows by Cygwin
      • Once the slave is online, run a test job on it that requires elevated permissions, such as starting/stopping the Spooler service
  2. There are additional caveats.

    1. Public key auth can cause issues with Visual Studio compilation. See https://cygwin.com/cygwin-ug-net/ntsec.html#ntsec-nopasswd3 and http://stackoverflow.com/questions/12325096/notorious-visual-studio-error-c1902-vs-configuration#comment37501198_12325096

    2. cygwin sshd does not set all environment variables.

  3. Windows UNC not works. e.g. the following command line fails with "Permission denied" (though it works from a normal ssh login)

    cd //a-remote-host

    A workaround is to map the network resource to a drive letter

    net use Z: '\\a-remote-host' 'password' '/user:domain\username'
    cd Z:/
    1. By printing out the environment variables, USERDOMAIN and USERNAME, it is verified that the user accessing the UNC is as expected, i.e. the same as used for manual ssh login.

Write a comment…