Cygwin HOWTO

Cygwin UNIX Tools for Windows

Overview

The Cygwin utilities are used to provide a means of using a Windows based PC to host the OASIS data download and processing software with a minimal porting effort. The open source Cygwin tools provide a very complete suite of UNIX tools and services, enabling the user to create a UNIX environment in which to run shell scripts and applications, and provide familiar UNIX shell interfaces to the PC, even under DOS shells. Many services, like cron and the inetd networking daemons, are also available, as are programming tools like gcc, make gdb, perl, and tcl, to name a few.

Cygwin, formerly maintained by Cygnus Systems, is now maintained by Red Hat. The Cygwin website at http://www.cygwin.com provides good support for this product.

This HOWTO describes how to install Cygwin and configure several services for use with the OASIS download software.

Table of Contents

Introduction
Hardware Requirements
Installarion Overview
Installation

Installing Cygwin
Setting Up Environment Variables
Setting Up Users

Setting Up Services

cron
inetd
ssmtp
mutt
anonymous ftp
sshd
minicom

Resources

Introduction

This HOWTO covers the installation of Cygwin, a Windows port of the UNIX
tools and services. Cygwin provides the software infrastructure for oasisnt, PC software to perform
real time scheduled data downloads from drifters and tethered moorings.

Hardware Requirements

• PC (P166, 32MB RAM, Serial Port, CDROM, Ethernet Adapter, 90 MB HDD space,
  Windows NT (must have administrator privledges), Winzip, Hyperterminal)
  
  
• Connection to Internet (for downloading Cygwin software)

Installation Overview

The Cygwin tools are downloaded from the Cygwin website using a setup program available there. The setup tool also acts as a package manager to help you incrementally update your installation. Cygwin components are grouped together as software packages; Since there dependencies between packages, it is recommended that you initially download all packages.

Packages may be installed as binaries or source. Unless you have a specific need to build a package yourself (for example, certain contributed packages like minicom don't have binary distributions), it will be easier and conserve disk space to install everything as binaries.

The installation procedure consists of these steps:

1. Use the Setup program to install Cygwin
2. Set up the environment variables
3. Set up users

Installation

Use the Setup Program to Install Cygwin

1. Create a directory in which to install Cygwin, preferably under root, e.g., C:\cygwin
2. Log on to http://www.cygwin.com
3. Click on the "Install Cygwin Now" link or icon
4. Choose to Open the Setup utility (or you may download it and run it from disk)
5. Select Install from Internet
6. Choose the install directory created in step 1 as the local package directory (e.g., C:\cygwin)
7. Choose the install directory created in step 1 as the Cygwin root directory
8. Select the Unix file type and Install for All options
9. Select Direct Connection
10. Select a mirror site from which to download the files
11. Select the packages you would like to install; If you are installing for the first time, all packages are
    selected and it is recommended that you do install all packages; they can be removed later if necessary.
    Clicking the Full/Part button will show more or fewer packages. Clicking the entries in the New column toggle which version (if any) is to be downloaded; Checking the box in the src column selects to download source for that package.
    For an initial installation, it is recommended to accept all defaults.
12. The packages will then be downloaded and installed, then you will prompted to optionally install toolbar and desktop icons.
    

Set Up the Environment Variables

Several environment variables need to be set to allow the Cygwin to work correctly. The Cygwin /bin directory (and other directories containing Cygwin executables) should be put into the DOS Path variable. There is also a CYGWIN environment variable that is used to configure Cygwin.

1. Open the NT Control Panel and choose the System setup utility.
2. Click the Environment tab.
3. Add the following System (not User) Environment variable:

   name: CYGWIN_PATH
   value: c:\cygwin\bin;c:\cygwin\usr\sbin;/usr/bin

4. Modify the PATH system environment variable for all users, adding the environment variables above:
   

   <your path>;%CYGWIN_PATH%

5. Add the following System (not User) Environment variables:

   name: CYGWIN
   value: tty ntsec

6. Reboot the computer (the system path will not update correctly for Cygwin until the computer is rebooted!)

Set Up Users

It is often convenient (and for installing some contributed packages, required) to have a local user named root who is a member of the administrators group in the PC's local domain. If you wish to do so, use the Administrative Tools to create and the root user and add them to the Administrators group.

If you will be setting up anonymous ftp, you will also need to create a user named ftp; ftp must belong to the Users group and have a blank password (allowing blank passwords may be enabled under the User Manager Policies menu option).

For login to work correctly, use the Policies>>User Rights menu option (select the Show Advanced option) to add the following user rights for Administrators ONLY:

• Act as part of the OS
• Replace Process Level Tokens
• Increase Quotas
• Log on as a Service

Note that these rights are not given even to administrators by default and should be granted with care.

Add any users that will need to login remotely and administer the system to the Telnet Access Group.

Setup the /etc/passwd file

1. Login to windows as the newly created root user.
2. Open a Cygwin session by clicking the desktop or Start>>Programs>>Cygnus Solutions>>Bash Shell
3. Change directory to /etc
4. Create the passwd file and add all local users using

mkpasswd -l > /etc/passwd

5. Add members of a Windows domain to the passwd file using

mkpasswd -d | grep username >> /etc/passwd

6. Edit the passwd file, making the following changes:
   • Delete the Guest user
   • Delete the Everyone user
   • Give root UID 0 and GID 513 (Administrators)
   • Optionally, change long, capitalized user names to short, lower case ones (e.g. Adminstrator->admin)
   • For domain users (e.g. LAGOON\smith), add the following field immediately BEFORE the S-... field:

     U-LAGOON\smith

     or for a local user (e.g. jones)

     U-jones

   • To ensure proper use of file creation masks, change the UID and GID for all domain users to match the values used elsewhere in the domain:

     quark::1796:513:Steve Quark uber geek,U-LAGOON\quark,S-1-5-21-...-1796:/home/quark:/bin/bash

     quark::435:544:Steve Quark uber geek,U-LAGOON\quark,S-1-5-21-...-1796:/home/quark:/bin/bash

     Here, 1796 is the UID assigned by the local domain, 513 is the local Users group; they have been changed to 435 (UID elsewhere in the LAGOON domain) and 544 (local Administrators group) respectively.

   • If you wish to change the home directory or default shell, change the last two fields. See the file /etc/shells for a list of available shells.

Note that the encrypted password field is not used on Windows NT, 2000 and XP.

If you are installing oasisnt, create a local user called oasis and add it to the local Administrators group.

Setup the /etc/group file

1. Create the group file using
   

mkgroup -l >> /etc/group

2. Edit the group file, making the following changes:
   • Optionally, you may delete Everyone, Guests, Power Users, Replicators groups or other, unused groups
   • Optionally, change long, capitalized user names to short, lower case ones (e.g. Adminstrators->admins)

Setting Up Services

There are a number of UNIX services made available by Cygwin that you may wish use. Of those presented here, only the cron service is required by oasisnt to schedule downloads and processing scripts. Cygwin allows many applications to be run as Windows services using the program cygrunsrv. Programs that run as services can remain active as long as the PC is on, even when no one is logged in.

Type cygrunsrv --help and consult the Cygwin documentation for more information.

cron

cron works very much like its UNIX counterpart; care must be taken to install it correctly. It is very important that users are set up in the manner prescribed. The following procedure may be used to set up cron:

1. Make sure that no other cron services are running
2. It is critical that the cron service be allowed to create the /var/cron and /var/log directories; if these exist for some reason (e.g., crontab has been run prior to installing and running cron for the first time), delete these directories and their contents
3. As the root user, install the cron service using

   cygrunsrv -I cron -p /usr/sbin/cron -a -D -e CYGWIN="tty ntsec"

4. Start the cron service using

   cygrunsrv -S cron

   ps -ef should indicate that the service is running. The directories /var/cron and /var/log should have been created.

5. crontab may now be used to create, edit, install and remove crontabs:

   usage: crontab [-u user] file
   crontab [-u user] { -e | -l | -r }
   (default operation is replace, per 1003.2)
   -e (edit user's crontab)
   -l (list user's crontab)
   -r (delete user's crontab)

6. Stop the cron service using

cygrunsrv -E cron

inetd

The inetd service comprises a number of network daemons, including telnet and ftp. Use the following procedure to install inetd:

1. Disable any existing network services
2. As root, run (in a cygwin shell)

iu-config

(This creates /etc/inetd.conf, /etc/shells, /etc/ftpusers, /etc/ftpwelcome, /etc/motd)

3. As root, run (in a cygwin shell)

   inetd --install-as-service

4. To start the inetd service, run

   net start inetd
   
   (ps -ef will indicate more than one process; this is 'normal')

5. To suspend the inetd service, use

   net stop inetd

6. To remove the inetd service use

   inetd --remove-as-service

ssmtp

ssmtp is an optional Cygwin package. oasisnt uses the ssmtp MTA to send email to a list of users when a download fails. If you do not want this capability, you may comment it out of get<mooring>, and skip this section.

1. As root, run

   config-ssmtp
   
   to create the ssmtp configuration file. You will be prompted for the
   
   host name (e.g., fish.shore.mbari.org)
   mail name (e.g. mbari.org)
   smtp server host name (e.g., cirrus.shore.mbari.org)
   smtp server port (e.g., 25).
   
   Note: The Cygwin ash package must be installed for this script to run,

2. In /etc/ssmtp.conf, uncomment rewriteDomain and set equal to mbari.org (your domain)
   

mutt

Mutt is an optional Cygwin package. oasisnt uses the mutt mail client to send email to a list of users when a download fails. If you do not want this capability, you may comment it out of get<mooring>, and skip this section. Note: The Cygwin ncurses and gettext packages must be installed for this mutt to run.

1. If it is not already installed, install the mutt package from the contrib directory
2. Uncomment the "set sendmail =" line in /etc/Muttrc and edit it to read:

   set sendmail = "/usr/sbin/ssmtp"
   

3. Uncomment the "set gecos_mask =" line in /etc/Muttrc, using the default value
4. Mutt -x ... emulates UNIX mailx (for use in shell scripts)

anonymous ftp

At this writing, anonymous ftp required the use of a special developer's snapshot of the Cygwin main dll that caused other things (most noteably cron) to break. If this has been fixed, you may create an anonymous ftp site as follows:

1. Create a local ftp user with a blank password as described above
2. Add the ftp user to the /etc/passwd file as described above
3. Setup the ftp directory structure and file permissions described in /usr/doc/Cygwin/inetutils-<version>.README file
4. Edit /etc/ftpusers and remove the user ftp (ironically, ftpusers are those who are NOT allowed ftp access)
5. Copy these files from /etc/ to <your ftp root>/etc/ (e.g., /home/ftp/etc)

   passwd
   group
   motd
   ftpusers
   ftpwelcome

6. Copy these files from /bin to <your ftp root>/bin/ (e.g., /home/ftp/bin)

   bash.exe
   cygwin1.dll
   false
   ls.exe

It should now be possible to ftp anonymously to the system, using ftp as the username and your email address as the password. At this writing, the FTP client used could not properly execute the ls command under some circumstances; using nlist did work as an alternative.

sshd

sshd is a secure remote login alternative to rlogin. The sshd daemon handles incoming ssh login requests.

1. As root, run

   ssh-host-config (create config files and server keys)

2. To add a user, (as user) run

   ssh-user-config (create user keys)

3. To install the sshd service, as root run

   cygrunsrv -I ssh -p /usr/sbin/sshd -a -D -e CYGWIN="binmode tty ntsec"

4. To start sshd via inetd,
   
   
   • copy sshd to /usr/sbin/in.sshd
   • add /usr/sbin/in.sshd to /etc/inetd.conf :
     
     ssh stream tcp nowait root /usr/sbin/in.sshd
     
     
   • add (if not there) line to %SYSTEMROOT%/system32/drivers/etc/services:
     
     ssh 22/tcp #ssh daemon

sftp

sftp is a secure remote login alternative to ftp. Install the sshd (above) and in /etc/sshd_config, uncomment Subsytem sftp /usr/sbin/sftp-server.

Note: At this writing, the sftp subsystem did not work correctly. It may have since been fixed.

minicom

minicom is a serial terminal program, similar to Telix and Procomm. It has the advantage of being able to be used from a text based terminal session, like telnet. It is a third-party contributed package and is a little bit buggy and tricky to install, but it may be worth the trouble if you need a remote serial terminal.

1. From http://www.eskimo.com/~ewu/cygwin/minicom1.83, download the source and patch, saving them to /cygwin/contrib/minicom
2. As root,

   cd /cygwin/contrib/minicom
   tar zxvf minicom...
   patch -p1 < minicom-cygwin.patch
   cd /minicom-1.83.1/src
   make
   If errors related to long lines occur, the source code may have lines that are too long for the compiler. If this happens, edit the source code and break the lines up into smaller lines and make again.
   

3. The install script (install.sh) has to be patched up to work with Cygwin:

   add .exe to minicom
   change root to admins
   change uucp to none

4. Install minicom:

   run make install
   copy /doc/minirc.dfl to /etc
   chown root minicom.exe
   chmod 777 /usr/local/*
   chown root /usr/local/*
   chgrp none /usr/local/*

5. Reboot the computer

Read the documentation and man page for more information about using minicom.

Resources

http://www.cygwin.com

The documentation under /usr/doc and /usr/doc/Cygwin contains a wealth of useful information
about setting up and using Cygwin services and applications

There are man pages available for almost all of the software in the Cygwin packages