OpenSSH on Windows v3.4-1 Mark Bradshaw mark@networksimplicity.com [Last Updated June 26, 2002] CONTENTS -------- Intro Installation Silent Installation Manual Uninstall Configuration Cygdrive Notation Key Authentication Terminal Emulation Remote Command Execution X11 Port Forwarding Remote Port Forwarding Firewalls Troubleshooting Source History Is This Trustworthy? Warranty Final Notes INTRO ----- This server should be used only on Windows NT, 2k, and XP. You can get it to work on 9x or ME, but I don't support it. If you're having problems getting the server portion to work feel free to contact me at mark@networksimplicity.com, but try everything here in the docs and try looking for answers on the WebBoard (http://www.networksimplicity.com/board). I don't guarantee any results of the software or my help, but if you've read through the docs here first I'll take a look at your problem. NOTE: This port uses the cygwin utilities, but is NOT designed to be run concurrently with them. If you have cygwin installed, this openssh server will use the cygwin environment, instead of the one I've packaged with it. Chaos ensues. Please don't do that, or don't expect miracles from me when the server doesn't function as advertised and cygwin breaks. [Taken from Cygwin docs] It is important that you understand the implications of Cygwin using shared memory areas to store information about Cygwin processes. Because these areas are not yet protected in any way, in principle a malicious user could modify them to cause unexpected behavior in Cygwin processes. While this is not a new problem under Windows 9x (because of the lack of operating system security), it does constitute a security hole under Windows NT. This is because one user could affect the Cygwin programs run by another user by changing the shared memory information in ways that they could not in a more typical WinNT program. For this reason, it is not appropriate to use Cygwin in high-security applications. In practice, this will not be a major problem for most uses of the library. Now on a practical level, can you trust the security of OpenSSH on Windows? The short answer is yes, as long as only trusted users log in. The security of OpenSSH itself is not watered down at all in this package. The only part of this package that is questionable is the cygwin subsystem itself. OpenSSH will keep unwanted users from logging on, but if you allow access to untrusted users you have negated your security. For this reason, I highly recommend using this OpenSSH server (in its current implementation) for admin users only. Do not allow normal users to connect on without fully trusting them, as they could potentially use the shared memory problems to compromise your security. INSTALLATION ------------ Installation is fairly straightforward. The archive contains one file, setup.exe. Run setup.exe and answer the questions that it asks. It'll make several directories in the location you choose and then copy files into their correct locations. It'll run ssh-keygen to create the host keys needed for server operation. It'll create a service, using Cygrunsrv, that runs the ssh server. Please remember to reboot after installation. On some machines, if you don't reboot, you'll authenticate fine but the connection will drop immediately after. A service called OpenSSHd has been installed for you. To launch OpenSSH start this service. SILENT INSTALLATION ------------------- You can install the OpenSSH package silently (meaning no GUI interaction required). This allows you to push the package to a remote server and install it there using the scheduler. By default it will install both the client and server packages to C:\Program Files\NetworkSimplicity. You can't select which packages to install, since you'll want both in a server installation, but you can change the install directory. You do this by setting an environment variable called SSH_INSTALL_DIRECTORY to the location of your choice. If you also want the installer to skip creating the Start Menu shortcuts add another environment variabled called SSH_NO_SHORTCUTS and set it equal to "yes". When you're ready to install you invoke the installer with the /s option (setup.exe /s). Please note that you should set the environment variable equal to the short name equivalent (8.3 naming scheme) of the directory name. You can see this by using dir with the /x option. It will list an additional column with the 8.3 name. In the above example, you might set SSH_INSTALL_DIRECTORY equal to C:\Progra~1\Networ~1. Probably the best way to make use of this option is via the Windows scheduler. You can launch it and add items remotely. MANUAL UNINSTALL ---------------- 1) Stop the opensshd service 2) Kill any sshd.exe and sh.exe processes left running 3) Go to your installation directory 4) Remove the /etc and /var directories 5) Remove everything in /ssh except the various host keys 6) You may or may not want to keep things in /ssh/.ssh depending on whether you were doing any key authentication. 7) In the registry, remove everything under HKLM\SOFTWARE\Cygnus Solutions. Just select "Cygnus Solutions" and hit delete. This is where the Cygwin mount table is kept. It's a good idea to also delete any "Cygnus Solutions" keys you find in user hives. Step number seven is very important, so make sure you get rid of that key. After that you should be good. You might also want to edit your system path to remove your openssh installation path from the beginning. CONFIGURATION ------------- The biggest hurdles to getting the server to run, so far, have been in setting up the passwd file. You have to have a passwd file in [INSTALL DIRECTORY]\etc that duplicates the functionality of the /etc/passwd file in Unix. The one that is supplied with the server installation is empty, and will not allow ANY logins until you've configured it further. Passwd editing has changed SIGNIFICANTLY in versions >= 3.0.1. The majority of user adding is done via the mkpasswd program. I've included mkgroup (identical to that distributed by cygwin) and a modified mkpasswd. Mkpasswd has been edited so that it uses /ssh as the default home directory, and /ssh/switch as the default shell. First, open a command prompt and move into your [INSTALL DIRECTORY]\ssh directory. You can use mkgroup to create an /etc/group file in [INSTALL DIRECTORY]\etc. This is necessary for correct operation, and is necessary if you want to enforce proper Windows permissions. To do that you would run: mkgroup -l >> ..\etc\group to add local groups, and: mkgroup -d >> ..\etc\group to add domain groups. Note that if you do both mkgroup commands you'll end up with a few duplicates. Remove those by hand. Now you'll use mkpasswd to add a line to your [INSTALL DIRECTORY]\etc\passwd file for each user that will login. If you have a local user called localjoe that should be allowed to login then type: mkpasswd -l -u localjoe >> ..\etc\passwd If you have a domain user called domainbob that should be allowed to login then type: mkpasswd -d -u domainbob >> ..\etc\passwd If you want to use mkpasswd with a user that is not in your primary domain then you must use a different syntax. If you wanted to get user jdoe from trusted domain trustdomain you would type: mkpasswd -d -u jdoe trustdomain >> ..\etc\passwd Note that you have some options on the very last portion of a user entry in passwd (after the last colon), which is your shell. The default shell is /ssh/switch, which should be appropriate for 99% of the users that you'll add. If you will be using scp or sftp I recommend using the switch.exe app I've included (/ssh/switch.exe). It will intelligently switch shells between cmd.exe and sh.exe depending on the function you are trying to do. This allows you to use cmd.exe as you ssh shell, but still work with scp and sftp. I've included full source to switch (which isn't long), so you can verify what it does and recompile if necessary. If you'll only be using the ssh app (no scp or sftp), you can set the shell to /ssh/quietcmd.bat (runs c:\winnt\system32\cmd.exe /q). If you get errors when logging in that point to an invalid setgid operation then check your group file. It should have a group line that matches up with the group id listed for your user in the passwd file. Occasionally these can get a bit out of sync, particulary for the None group (513 or 10513). Here's some tips that I've found to be useful: 1) Make sure the service is running under the SYSTEM account. It has to have access to some privileges that administrator accounts doesn't have by default. If you've switched it, switch it back. 2) If you want to use the ssh client FROM the server, you might want to make the home directory field some other directory than root (/). This gets around a small directory problem in the ssh client. I usually use /ssh. 3) NO ONE should have a crypt entry in the password field (second field) of the passwd file. NT authentication is used, so leave the second field alone/blank. If you receive an error "You don't exist, go away!" then you have an incomplete [INSTALL DIRECTORY]\etc\passwd file. If you're on a Windows 9x or ME machine, and are only using the client, then look for a file called [INSTALL DIRECTORY]\etc\passwd and rename it to something else. If you have installed the server, then you should add a line to the passwd file for your current user. The ssh utilities search this file for your current user to determine where to find various files, and since you aren't listed it gives an error. CYGDRIVE NOTATION ----------------- If you want to specify alternate drives when using scp or sftp, or you'd like to have home directories that aren't on the C drive then you must use the special cygdrive notation. This is how the notion of "drive letters" is mapped onto OpenSSH's native unix style file system. If you want to specify a different drive other than C, you do this by using the /cygdrive/DRIVE_LETTER/ notation. For instance, if you wanted to transfer file.txt to d:\temp on the target server using scp the command would be: scp file.txt user@server:/cygdrive/d/temp/ KEY AUTHENTICATION ------------------ For information regarding key authentication with the SSH server refer to key_authentication.txt. TERMINAL EMULATION ------------------ When using the client to connect to other (non Windows/openssh) servers you may notice that some key strokes don't do what you'd expect (or nothing at all). This is generally due to terminal differences. When the cygwin/openssh client connects it sets the TERM variable to cygwin, which some other OS's don't recognize. In this case, you must tell them what the cygwin term is. On unix machines you can usually do this by editing /etc/termcap and adding the following lines: cygwin:\ :xn@:op=\E[39;49m:Km=\E[M:te=\E[2J\E[?47l\E8:ti=\E7\E[?47h:tc=linux: On the other hand, if your *nix uses terminfo files, instead of the termcap file, then you can upload the "cgywin-terminfo" file, located in your [INSTALL DIRECTORY]\ssh directory, to your server in the appropriate location. Remember to rename the file from "cygwin-terminfo" to "cygwin". Usually terminfo files are in /usr/share/terminfo, or /usr/share/lib/terminfo. REMOTE COMMAND EXECUTION ------------------------ One nice feature of the ssh client is that you can specify a command to execute, instead of getting a shell. This is very handy for creating scripts to stop/start services, etc, where you don't want to actually type in all the commands yourself. You can instead specify them in a batch file and, using key authentication instead of passwords to log in, have them remotely executed. To specify a command to execute with the openssh client you must format it in a special way: ssh user@server command Replace "command" with your command and it'll be executed. Any output will be returned to you. This assumes that you are using switch.exe as your shell. If you are using cmd.exe, or are using switch but need to execute a cmd.exe command (such as dir), then you should use the following command structure: ssh user@server cmd /c command Replace "command" with your command and it'll be executed. Any output will be returned to you. X11 PORT FORWARDING ------------------- ####### UPDATE: With some preliminary tests it appears that the following info is no longer valid. You'll probably get the most bang for you buck by manually doing remote port forwarding as follows: ssh -R 6000:localhost:6000 user@remoteserver.domain.com This means you'd set the remote DISPLAY variable to :0.0 ####### OpenSSH supports X11 port forwarding for X11 apps. This allows you to send all X11 traffic over an encrypted tunnel, and so secure your remote server. This is generally done automatically on unix machines, but under windows no such dice. This is because the ssh client will only set up X11 forwarding when it detects that it's inside an X environment, which windows is not even if it's running X server software. Fortunately it's fairly easy to fix this. The client looks for the existence of an environment variable called DISPLAY to determine if X is running. In order to trick it you simply need to create this environment variable. The value of the DISPLAY variable should be of the form LOCAL_IP_ADDRESS:0.0. You can type: set DISPLAY=172.16.1.1:0.0 at the command line, or make a more permanent change by creating an environment variable in your computer properties. Then you just add the -X option to your client command line. Ex. ssh -X user@server.domain.com You may see a warning here that a file called xauth doesn't exist. Don't worry. This is OK. After you log in it'll set up your DISPLAY and XAUTHORITY variables correctly. Don't reset them manually! Launch a local X server on your windows machine (such as WinAxe) and enjoy! REMOTE PORT FORWARDING ---------------------- Keep in mind that server's won't allow anyone other than themselves to connect to remotely forwarded ports unless you specify the following line in the [INSTALL DIRECTORY]\ssh\sshd_config file: GatewayPorts yes FIREWALLS --------- The server responds by default on TCP port 22. The client will connect from a random TCP port. In order to allow ssh traffic through your firewall simply allow through TCP traffic on port 22. TROUBLESHOOTING --------------- Here's a few notes that might help you identify your problem: 1) Make sure the service is running under the SYSTEM account. It has to have access to some privileges that administrator accounts doesn't have by default. If you've switched it, switch it back. 2) If you want to use the ssh client FROM the server, you might want to make the home directory field some other directory than root (/). This gets around a small directory problem in the ssh client. I usually use /ssh. 3) NO ONE should have a crypt entry in the password field (second field) of passwd. NT authentication is used, so leave the second field alone/blank. 4) Please note that though this package is taken from the cygwin port of OpenSSH, it is NOT designed to run concurrently with cygwin. If you have cygwin installed this OpenSSH server will either not work, or will cause cygwin to stop working. Actually, both are likely. Don't do it. You may have have differing versions of cygwin1.dll installed even if you've never installed cygwin itself. Many unix utilities that have been ported with the cygwin package include a version of the dll. If you have older versions it can cause this server to function incorrectly. Do a search for cygwin1.dll and rename any alternate copies. 5) If you get a "Could not create directory '//.ssh'" or "Cannot create //.ssh" error when using the clients then you need to correctly configure your [INSTALL DIRECTORY]\etc\passwd file. Add a line for your current user (on the client side). Use the directions in the Configuration section above. 6) If the user has cygwin mount information in the registry under the HKEY_CURRENT_USER hive it can mess up switch. This means that you'll authenticate fine, but will be immediately disconnected. Log onto the server as the user having trouble and look in the registry under HKEY_CURRENT_USER. If you locate a key called "Cygnus Solutions" delete the entire key. Note that there will be a "Cygnus Solutions" key in HKEY_LOCAL_MACHINE. Don't delete it. 7) Make sure that when you are stop and starting the service all cygrunsrv and sshd processes are being killed. If you have the resource kit use "kill" to stop the processes. Otherwise, try pskill. It's a part of the pstools package from SysInternals.com. 8) If the OpenSSHd service refuses to start check the Computer Browser service. The OpenSSHd service depends on the Computer Browser service so that it starts in the correct order. You or someone else may have disabled the Computer Browser service. If you'd like to have the OpenSSHd service depend on some other service you can change the setting at: HKLM\SYSTEM\CurrentControlSet\Services\opensshd\DependOnService If these tips don't help and you want to contact me, please use the following procedure to run sshd in debug mode and capture it's output. 1) Start the scheduler service. (net start schedule or net start "task scheduler") 2) type the following at the command line: at /interactive c:\winnt\system32\cmd.exe substitute a time inside the brackets (like 7:15PM), and use the proper path to cmd. 3) At the specified time a SYSTEM owned cmd shell should show up. 4) Make sure QuickEdit mode is turned on. You turn it on by right-clicking on the title bar. Select Properties. On the options tab check the QuickEdit box. Hit OK and choose to save. 5) In that cmd shell move to your [INSTALL DIRECTORY]\ssh directory 6) type: set CYGWIN=ntsec tty 7) type: sshd -d -d -d -f sshd_config This launches sshd in debug mode (the -d's). If it launches try to connect to it from a client. Whether it launches or not capture the output and send it to me. You can copy and paste from the box (using QuickEdit mode) by selecting the text with your mouse and right clicking. That will copy the text to the clipboard. Then open notepad and paste it in. SOURCE ------ The OpenSSH utilities are based off freely available source. You can download them from http://www.openssh.com. Cygwin is a great set of utilities for porting unix utilities over to windows. You can download and install it from http://www.cygwin.com. Source for switch is included with the package. Source for various other pieces can be found at: http://www.networksimplicity.com/openssh/source/ HISTORY ------- In late 2000 my company, which uses a duke's mixture of Solaris, Linux, and Windows needed a unified remote console program. We had been using ssh to connect to the *nix machines, but using telnet to connect to the Windows. We did this because telnet was free and available. I finally got fed up with the current state and set out to find a freeware SSH server for Windows. A few days later I had to come to the conclusion that such an animal just didn't exist. The closest thing I found was the package OpenSSH package that came with cygwin. However, at the time it had no built-in service support, used a unixized shell, and was WAY too bulky for server use (IMO). Around the same time I was contact by Penton Media about doing an article for Windows 2000 magazine. It occurred to me that here was the perfect subject matter. I was sure that I wasn't the only person currently looking for a free Windows server, so I decided to combine the two, do the article research and get an OpenSSH package made. The article was written in December, and shortly thereafter I had a packaged installer for OpenSSH. I shudder when I remember the "installer" of that first package, which was a cranky batch file, but it worked. I made a few efforts at making it more generic and put it up on my web site. Wonder of wonders, people actually used it. They found some bugs, and so did I. I would correct them and drop a new version on the web site and repeat the whole process. Eventually my own embarassment made me get serious with the installer. The batch file just looked and felt ridiculous, so I went on a search for a freeware installer package. The one I chose was Installer Vise, which allowed you to make free installers for freeware/shareware projects. I used that, and came up with my first "real" installer. I think it was around the same time that the outcry for easy scp support got to the point where I felt the need to deal with the problem. Because I had made the decision to run with the standard Windows shell, instead of using Cygwin's ash or bash, I had a couple of problems to deal with. The first was that scp and sftp rely on /bin/sh syntax for launching the remote side of the file transfer connection. The Windows shell didn't support that syntax, so you had to have multiple logins for different functions. To correct this behavior I made switch, a simple shell switcher that basically just checks for the /bin/sh syntax being passed across and launches sh.exe if necessary. A simple concept, but one that made the whole ball of wax function. :o) Up to this time I had not packaged sftp, because I found out that it had real problems. The sftp app would hang whenever someone asked for a directory listing, and wouldn't do transfers of any kind to the root directory. I had been getting more and more involved in both Cygwin and OpenSSH, so I decided it was time that the problem be solved. Others had been posting requests for help on the cygwin mailing list, but no one had yet tracked down the problem. After a bit of deductive work I found a few odds and ends problems with both OpenSSH and Cygwin that have since been patched (mostly). Both OpenSSH and Cygwin continue to improve, and it's getting to the point where the tools to do most of the conversion work I did the hard way are working out of the box. I don't know how long I'll continue to support a separate package from Cygwin's. I think I'll keep doing it as long as I find it useful, and people keep downloading it. IS THIS TRUSTWORTHY? -------------------- I occasionally get queries asking how I can be trusted to produce an unhacked package. Unfortunately I don't get as many as I'd like. I think with software that deals so intimately with your security, you should be a bit more concerned about who makes it. I hope the following helps those that ARE concerned. My package has been in circulation, in various forms, since late 2000. In that time I have never had a complaint regarding security, and only once had someone suggest that the installer caused a problem on their machine. It has been downloaded (as of December 2001 for the sites I can track) close to 100,000 times, and seems to be working fine for most people. I currently work as the Senior Engineer for a Christian Internet Media company called Crosswalk.com, based outside Washington, DC. I have a serious interest in security, and would consider myself a well-trained systems administrator (not a security administrator). I have completed most of the training for the SANS GIAC certification. I have a good familiarity with security in general, and network security in specific. I've been a network/systems admin for 7+ years, and have contributed to both the OpenSSH and Cygwin projects, though I'm not a core developer for either. I don't provide the source for OpenSSH, because the source is freely available from the OpenSSH site. Corinna Vinschen at Redhat does a lot of work to make it compile out of the box in Cygwin, so there's no need for me to distribute the same source again. I belive that you have to determine your own level of comfort here. If you trust the OpenBSD Project guys, then get their source and run it on *nix boxes that support it. If you trust the Red Hat folks that do Cygwin, and all the volunteers that contribute, to get their POSIX layer right, then by all means grab the cygwin package and do a native OpenSSH installation. If you feel that I'm trustworthy, however, you can save yourself some time. I'd just like to note that this package isn't something I just do for other people. It's primarily for my own use. I believe that the chef should eat his own cooking, so the package that's downloadable from the site is EXACTLY the same as the one I use in my own installations. WARRANTY -------- NO WARRANTY BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. FINAL NOTES ----------- I hope you enjoy this package. It's worked great for me, and seems to be working fine for most people. If you have any suggestions feel free to pipe up. This is a work in progress, and I can always use the help! If you've enjoyed the package you can show your appreciation by sending me a CD from my wishlist. http://www.amazon.com/exec/obidos/wishlist/NFYAC42GQTXI/ref=wl_em_to?add-fav=1 The installer for this product was created using Installer VISE from MindVision Software. For more information on Installer VISE, contact: MindVision Software 5901 North 58th Street Lincoln, NE 68507-3249 Voice: (402) 323-6600 Fax: (402) 323-6611 E-mail: mindvision@mindvision.com http://www.mindvision.com -Mark mark@networksimplicity.com