[gssapi-openssh.git] / openssh / contrib / cygwin / README

This package is the actual port of OpenSSH to Cygwin 1.5.

===========================================================================
Important change since 3.4p1-2:

This version adds privilege separation as default setting, see
/usr/doc/openssh/README.privsep.  According to that document the
privsep feature requires a non-privileged account called 'sshd'.

The new ssh-host-config file which is part of this version asks
to create 'sshd' as local user if you want to use privilege
separation.  If you confirm, it creates that NT user and adds
the necessary entry to /etc/passwd.

On 9x/Me systems the script just sets UsePrivilegeSeparation to "no"
since that feature doesn't make any sense on a system which doesn't
differ between privileged and unprivileged users.

The new ssh-host-config script also adds the /var/empty directory
needed by privilege separation.  When creating the /var/empty directory
by yourself, please note that in contrast to the README.privsep document
the owner sshould not be "root" but the user which is running sshd.  So,
in the standard configuration this is SYSTEM.  The ssh-host-config script
chowns /var/empty accordingly.
===========================================================================

===========================================================================
Important change since 3.0.1p1-2:

This version introduces the ability to register sshd as service on
Windows 9x/Me systems.  This is done only when the options -D and/or
-d are not given.
===========================================================================

===========================================================================
Important change since 2.9p2:

Since Cygwin is able to switch user context without password beginning
with version 1.3.2, OpenSSH now allows to do so when it's running under
a version >= 1.3.2. Keep in mind that `ntsec' has to be activated to
allow that feature.
===========================================================================

===========================================================================
Important change since 2.3.0p1:

When using `ntea' or `ntsec' you now have to care for the ownership
and permission bits of your host key files and your private key files.
The host key files have to be owned by the NT account which starts
sshd. The user key files have to be owned by the user. The permission
bits of the private key files (host and user) have to be at least
rw------- (0600)!

Note that this is forced under `ntsec' only if the files are on a NTFS
filesystem (which is recommended) due to the lack of any basic security
features of the FAT/FAT32 filesystems.
===========================================================================

If you are installing OpenSSH the first time, you can generate global config
files and server keys by running
   
   /usr/bin/ssh-host-config

Note that this binary archive doesn't contain default config files in /etc.
That files are only created if ssh-host-config is started.

If you are updating your installation you may run the above ssh-host-config
as well to move your configuration files to the new location and to
erase the files at the old location.

To support testing and unattended installation ssh-host-config got
some options:

usage: ssh-host-config [OPTION]...
Options:
    --debug      -d        Enable shell's debug output.
    --yes        -y        Answer all questions with "yes" automatically.
    --no         -n        Answer all questions with "no" automatically.
    --port       -p <n>    sshd listens on port n.

Additionally ssh-host-config now asks if it should install sshd as a
service when running under NT/W2K. This requires cygrunsrv installed.

You can create the private and public keys for a user now by running

  /usr/bin/ssh-user-config

under the users account.

To support testing and unattended installation ssh-user-config got
some options as well:

usage: ssh-user-config [OPTION]...
Options:
    --debug      -d        Enable shell's debug output.
    --yes        -y        Answer all questions with "yes" automatically.
    --no         -n        Answer all questions with "no" automatically.
    --passphrase -p word   Use "word" as passphrase automatically.

Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
(results in very slow deamon startup!) or from the command line (recommended
on 9X/ME).

If you start sshd as deamon via cygrunsrv.exe you MUST give the
"-D" option to sshd. Otherwise the service can't get started at all.

If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
following line to your inetd.conf file:

ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i

Moreover you'll have to add the following line to your
${SYSTEMROOT}/system32/drivers/etc/services file:

   ssh         22/tcp          #SSH daemon

===========================================================================
The following restrictions only apply to Cygwin versions up to 1.3.1
===========================================================================

Authentication to sshd is possible in one of two ways.
You'll have to decide before starting sshd!

- If you want to authenticate via RSA and you want to login to that
  machine to exactly one user account you can do so by running sshd
  under that user account. You must change /etc/sshd_config
  to contain the following:

  RSAAuthentication yes

  Moreover it's possible to use rhosts and/or rhosts with
  RSA authentication by setting the following in sshd_config:

  RhostsAuthentication yes
  RhostsRSAAuthentication yes

- If you want to be able to login to different user accounts you'll
  have to start sshd under system account or any other account that
  is able to switch user context. Note that administrators are _not_
  able to do that by default! You'll have to give the following
  special user rights to the user:
  "Act as part of the operating system"
  "Replace process level token"
  "Increase quotas"
  and if used via service manager
  "Logon as a service".

  The system account does of course own that user rights by default.

  Unfortunately, if you choose that way, you can only logon with
  NT password authentification and you should change
  /etc/sshd_config to contain the following:

    PasswordAuthentication yes
    RhostsAuthentication no
    RhostsRSAAuthentication no
    RSAAuthentication no

  However you can login to the user which has started sshd with
  RSA authentication anyway. If you want that, change the RSA
  authentication setting back to "yes":
     
    RSAAuthentication yes

Please note that OpenSSH does never use the value of $HOME to
search for the users configuration files! It always uses the
value of the pw_dir field in /etc/passwd as the home directory.
If no home diretory is set in /etc/passwd, the root directory
is used instead!

You may use all features of the CYGWIN=ntsec setting the same
way as they are used by the `login' port on sources.redhat.com:

  The pw_gecos field may contain an additional field, that begins
  with (upper case!) "U-", followed by the domain and the username
  separated by a backslash.
  CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
  BTW: The field separator in pw_gecos is the comma.
  The username in pw_name itself may be any nice name:

    domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...

  Now you may use `domuser' as your login name with telnet!
  This is possible additionally for local users, if you don't like
  your NT login name ;-) You only have to leave out the domain:

    locuser::1104:513:John Doe,U-user,S-1-5-21-...

SSH2 server and user keys are generated by the `ssh-*-config' scripts
as well.

If you want to build from source, the following options to
configure are used for the Cygwin binary distribution:

	--prefix=/usr \
	--sysconfdir=/etc \
	--libexecdir='${exec_prefix}/sbin'

You must have installed the zlib and openssl packages to be able to
build OpenSSH!

Please send requests, error reports etc. to cygwin@cygwin.com.

Have fun,

Corinna Vinschen <vinschen@redhat.com>
Cygwin Developer
Red Hat Inc.
Commit	Line	Data
acc3d05e	1	This package is the actual port of OpenSSH to Cygwin 1.5.
3c0ef626	2
41b2f314	3	===========================================================================
	4	Important change since 3.4p1-2:
	5
	6	This version adds privilege separation as default setting, see
	7	/usr/doc/openssh/README.privsep. According to that document the
	8	privsep feature requires a non-privileged account called 'sshd'.
	9
	10	The new ssh-host-config file which is part of this version asks
	11	to create 'sshd' as local user if you want to use privilege
	12	separation. If you confirm, it creates that NT user and adds
	13	the necessary entry to /etc/passwd.
	14
	15	On 9x/Me systems the script just sets UsePrivilegeSeparation to "no"
	16	since that feature doesn't make any sense on a system which doesn't
	17	differ between privileged and unprivileged users.
	18
	19	The new ssh-host-config script also adds the /var/empty directory
	20	needed by privilege separation. When creating the /var/empty directory
	21	by yourself, please note that in contrast to the README.privsep document
	22	the owner sshould not be "root" but the user which is running sshd. So,
	23	in the standard configuration this is SYSTEM. The ssh-host-config script
	24	chowns /var/empty accordingly.
	25	===========================================================================
	26
e9a17296	27	===========================================================================
	28	Important change since 3.0.1p1-2:
	29
	30	This version introduces the ability to register sshd as service on
	31	Windows 9x/Me systems. This is done only when the options -D and/or
	32	-d are not given.
	33	===========================================================================
	34
3c0ef626	35	===========================================================================
	36	Important change since 2.9p2:
	37
	38	Since Cygwin is able to switch user context without password beginning
	39	with version 1.3.2, OpenSSH now allows to do so when it's running under
	40	a version >= 1.3.2. Keep in mind that `ntsec' has to be activated to
	41	allow that feature.
	42	===========================================================================
	43
	44	===========================================================================
	45	Important change since 2.3.0p1:
	46
	47	When using `ntea' or `ntsec' you now have to care for the ownership
	48	and permission bits of your host key files and your private key files.
	49	The host key files have to be owned by the NT account which starts
	50	sshd. The user key files have to be owned by the user. The permission
	51	bits of the private key files (host and user) have to be at least
	52	rw------- (0600)!
	53
	54	Note that this is forced under `ntsec' only if the files are on a NTFS
	55	filesystem (which is recommended) due to the lack of any basic security
	56	features of the FAT/FAT32 filesystems.
	57	===========================================================================
	58
	59	If you are installing OpenSSH the first time, you can generate global config
	60	files and server keys by running
	61
	62	/usr/bin/ssh-host-config
	63
	64	Note that this binary archive doesn't contain default config files in /etc.
	65	That files are only created if ssh-host-config is started.
	66
	67	If you are updating your installation you may run the above ssh-host-config
	68	as well to move your configuration files to the new location and to
	69	erase the files at the old location.
	70
	71	To support testing and unattended installation ssh-host-config got
	72	some options:
	73
	74	usage: ssh-host-config [OPTION]...
	75	Options:
	76	--debug -d Enable shell's debug output.
	77	--yes -y Answer all questions with "yes" automatically.
	78	--no -n Answer all questions with "no" automatically.
	79	--port -p <n> sshd listens on port n.
	80
	81	Additionally ssh-host-config now asks if it should install sshd as a
	82	service when running under NT/W2K. This requires cygrunsrv installed.
	83
	84	You can create the private and public keys for a user now by running
	85
	86	/usr/bin/ssh-user-config
	87
	88	under the users account.
	89
	90	To support testing and unattended installation ssh-user-config got
	91	some options as well:
	92
	93	usage: ssh-user-config [OPTION]...
	94	Options:
	95	--debug -d Enable shell's debug output.
	96	--yes -y Answer all questions with "yes" automatically.
	97	--no -n Answer all questions with "no" automatically.
	98	--passphrase -p word Use "word" as passphrase automatically.
99
100	Install sshd as daemon via cygrunsrv.exe (recommended on NT/W2K), via inetd
101	(results in very slow deamon startup!) or from the command line (recommended
102	on 9X/ME).
103
104	If you start sshd as deamon via cygrunsrv.exe you MUST give the
105	"-D" option to sshd. Otherwise the service can't get started at all.
106
107	If starting via inetd, copy sshd to eg. /usr/sbin/in.sshd and add the
108	following line to your inetd.conf file:
109
e9a17296	110	ssh stream tcp nowait root /usr/sbin/in.sshd sshd -i
3c0ef626	111
	112	Moreover you'll have to add the following line to your
	113	${SYSTEMROOT}/system32/drivers/etc/services file:
	114
e9a17296	115	ssh 22/tcp #SSH daemon
3c0ef626	116
	117	===========================================================================
	118	The following restrictions only apply to Cygwin versions up to 1.3.1
	119	===========================================================================
	120
	121	Authentication to sshd is possible in one of two ways.
	122	You'll have to decide before starting sshd!
	123
	124	- If you want to authenticate via RSA and you want to login to that
	125	machine to exactly one user account you can do so by running sshd
	126	under that user account. You must change /etc/sshd_config
	127	to contain the following:
	128
	129	RSAAuthentication yes
	130
	131	Moreover it's possible to use rhosts and/or rhosts with
	132	RSA authentication by setting the following in sshd_config:
	133
	134	RhostsAuthentication yes
	135	RhostsRSAAuthentication yes
	136
	137	- If you want to be able to login to different user accounts you'll
	138	have to start sshd under system account or any other account that
	139	is able to switch user context. Note that administrators are _not_
	140	able to do that by default! You'll have to give the following
	141	special user rights to the user:
	142	"Act as part of the operating system"
	143	"Replace process level token"
	144	"Increase quotas"
	145	and if used via service manager
	146	"Logon as a service".
	147
	148	The system account does of course own that user rights by default.
	149
	150	Unfortunately, if you choose that way, you can only logon with
	151	NT password authentification and you should change
	152	/etc/sshd_config to contain the following:
	153
	154	PasswordAuthentication yes
	155	RhostsAuthentication no
	156	RhostsRSAAuthentication no
	157	RSAAuthentication no
	158
	159	However you can login to the user which has started sshd with
	160	RSA authentication anyway. If you want that, change the RSA
	161	authentication setting back to "yes":
	162
	163	RSAAuthentication yes
	164
	165	Please note that OpenSSH does never use the value of $HOME to
	166	search for the users configuration files! It always uses the
	167	value of the pw_dir field in /etc/passwd as the home directory.
	168	If no home diretory is set in /etc/passwd, the root directory
	169	is used instead!
	170
	171	You may use all features of the CYGWIN=ntsec setting the same
	172	way as they are used by the `login' port on sources.redhat.com:
	173
	174	The pw_gecos field may contain an additional field, that begins
	175	with (upper case!) "U-", followed by the domain and the username
	176	separated by a backslash.
	177	CAUTION: The SID _must_ remain the _last_ field in pw_gecos!
	178	BTW: The field separator in pw_gecos is the comma.
	179	The username in pw_name itself may be any nice name:
180
181	domuser::1104:513:John Doe,U-domain\user,S-1-5-21-...
182
183	Now you may use `domuser' as your login name with telnet!
184	This is possible additionally for local users, if you don't like
185	your NT login name ;-) You only have to leave out the domain:
186
187	locuser::1104:513:John Doe,U-user,S-1-5-21-...
188
189	SSH2 server and user keys are generated by the `ssh-*-config' scripts
190	as well.
191
192	If you want to build from source, the following options to
193	configure are used for the Cygwin binary distribution:
194
195	--prefix=/usr \
196	--sysconfdir=/etc \
e9a17296	197	--libexecdir='${exec_prefix}/sbin'
3c0ef626	198
700318f3	199	You must have installed the zlib and openssl packages to be able to
700318f3	200	build OpenSSH!
3c0ef626	201
	202	Please send requests, error reports etc. to cygwin@cygwin.com.
	203
	204	Have fun,
	205
	206	Corinna Vinschen <vinschen@redhat.com>
	207	Cygwin Developer
	208	Red Hat Inc.