diff --git a/INSTALL.txt b/INSTALL.txt index b4e4609c8a..a325811847 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -314,11 +314,24 @@ Roughly, the steps are so that it redirects to the given URL when a remote search is necessary. + Add `SERVER_PORT=...' to the `server' line to choose the port on + which the server listens to clients. The default is port 9440. + + Add `SERVER_HOSTS="..."' to determine the interfaces at which the + server listens. The default is "localhost" which listens only on + the loopback device (for security). Supply the empty string to + listen on all interfaces. Supply multiple addresses by separating + them with a comma. + 2. On each client machine: make client SERVER=... PKGS="..." or nmake win32-client SERVER=... PKGS="..." + Add `SERVER_PORT=...' to the `client' line if you picked an + alternate port in the `server` line; it shoul dbe the same as for + the `server' line. + Add `DOC_SEARCH="..."' to the `client' line, if needed; normally, it should be the same as for the `server' line. @@ -356,16 +369,19 @@ In more detail: 1a. Build "racket" on a server. The `base' target of the makefile will do that, if you haven't - done it already. On Windows, use `nmake win32-base'. + done it already. (The server only works on non-Windows platforms, + currently.) 1b. On the server, build packages and start a catalog server. - The `server-from-base' target of the makefile will do that. (The - server only works on non-Windows platforms, currently.) + The `server-from-base' target of the makefile will do that. Alternatively, use the `server' target, which combines `base' and `server-from-base' (i.e., steps 1a and 1b). + The `SERVER_PORT' and `SERVER_HOSTS' variables of the makefile + configure the prt and interfaces of the server. + The `PKGS' variable of the makefile determines which packages are built for potential inclusion in a distribution. @@ -396,8 +412,15 @@ In more detail: 2b. On each client, create an installer. The `client' (or `win32-client') target of the makefile will do - that. Provide `SERVER' as the hostname of the server machine, and - provide the same `PKGS' (or a subset) as in step 1b if you want a + that. + + Provide `SERVER' as the hostname of the server machine, but a + "locahost"-based tunnel back to the server is more secure and + avoids the need to specify `SERVER_HOSTS' when starting the + server in step 1b. Also, provide `SERVER_PORT' if an alternate + port was specified in step 1b. + + Provide the same `PKGS' (or a subset) as in step 1b if you want a different set than the ones listed in the makefile. Similarly, `DOC_SEARCH' normally should be the same as in step 1b, but for a client, it affects future documentation builds in the diff --git a/Makefile b/Makefile index 5225432c6f..746a96e636 100644 --- a/Makefile +++ b/Makefile @@ -119,11 +119,12 @@ DOC_SEARCH = # server): SERVER = localhost SERVER_PORT = 9440 + # Set `SERVER_HOSTS` to a comma-delimited set of server addresses -# that determine the interfaces on which the server listens; for -# example, set SERVER_HOSTS to "localhost" to listen only on the -# loopback device: -SERVER_HOSTS = +# that determine the interfaces on which the server listens; the +# default, "localhost", listens only on the loopback device, while +# anf empty value listens on all interfaces: +SERVER_HOSTS = localhost # Set to "--release" to create release-mode installers (as opposed to # snapshot installers): diff --git a/pkgs/distro-build/doc.txt b/pkgs/distro-build/doc.txt index 6c222b2d19..e556326ae5 100644 --- a/pkgs/distro-build/doc.txt +++ b/pkgs/distro-build/doc.txt @@ -24,13 +24,16 @@ client machines hierarchically, where configuration options propagate down the hierarchy when they are not overridden more locally. -Each client is normally built by running commands via `ssh', where -the client's host, `#:host' (with and optional `#:port' and/or -`#:user') indicate the SSH target. Each client machine must be set -up with a public-key authentication, because a direct `ssh' is -expected to work without a password prompt. An exception is when -the host is "localhost" and user is #f, in which case a shell is -used directly instead of `ssh'. +Each client is normally built by running commands via `ssh', where the +client's host, `#:host' (with and optional `#:port' and/or `#:user') +indicate the `ssh' target. Each client machine must be set up with a +public-key authentication, because a direct `ssh' is expected to work +without a password prompt. An exception is when the host is +"localhost" and user is #f, in which case a shell is used directly +instead of `ssh'. When `ssh` is used, -R is also used to create a +tunnel back to the server, and the client by default uses that tunnel +for all communication, and the server by default accepts only +connections via "localhost". On the client machine, all work is performed at a specified directory as specified by `#:dir'. The directory defaults to @@ -54,7 +57,7 @@ Normally, the client directory is a git clone: that the server and client are in sync), which means that the server's directory must be a git clone. -Note that neither SSH nor git turn out to be needed when the host +Note that neither `ssh' nor `git' turn out to be needed when the host is "localhost", the user is #f, and the directory is not specified (which corresponds to the defaults in all cases). @@ -124,22 +127,23 @@ Site-configuration keywords (where means no spaces, etc.): #:server --- the address of the server as accessed by the client; when ssh remote tunneling works, then "localhost" should - always work to reach the server; defaults to the `SERVER' makefile + work to reach the server; defaults to the `SERVER' makefile variable, which in turn defaults to "localhost" #:server-port --- the port of the server as accessed by - the client, and a port used on clients to tunnel back to the - server; defaults to the `SERVER_PORT' makefile variable, which in - turn defaults to 9440 + the client, and also the port started on clients to tunnel back to + the server; defaults to the `SERVER_PORT' makefile variable, which + in turn defaults to 9440 #:server-hosts --- addresses that determine the interfaces on which the server listens; an empty list means all of - the server's interface, while '("localhost") would listen only on - the loopback device; defaults to the `SERVER_HOSTS` makefile - variable split on comma, which in turn defaults to the empty list + the server's interfaces, while `(list "localhost")' listens only + on the loopback device; defaults to the `SERVER_HOSTS` makefile + variable split on commas, which in turn defaults to `(list + "localhost")' #:repo --- the git repository for Racket; defaults to - "http://:9440/.git" + "http://:/.git" #:pkgs '( ...) --- packages to install; defaults to the `PKGS' makefile variable @@ -467,12 +471,12 @@ installers might look like this: (sequential #:pkgs '("drracket") + #:server-hosts '() ; Insecure? See below. (machine #:desc "Linux (32-bit, Precise Pangolin)" #:name "Ubuntu 32" #:vbox "Ubuntu 12.04" - #:host "192.168.56.102" - #:server "192.168.56.1") + #:host "192.168.56.102") (machine #:desc "Windows (64-bit)" #:name "Windows 64" @@ -483,9 +487,22 @@ installers might look like this: #:bits 64)) The configuration describes using the hosts "192.168.56.1" and -"192.168.56.103" for Linux and Windows builds, respectively, which are -run one at a time. Furthermore, the Linux machine runs in VirtualBox -on the server machine (in a virtual machine named "Ubuntu 12.04"). +"10.0.0.7" for Linux and Windows builds, respectively, which are run +one at a time. + +The Linux machine runs in VirtualBox on the server machine (in a +virtual machine named "Ubuntu 12.04"). It contacts the server still as +"localhost", and that works because the ssh connection to the Linux +machine creates a tunnel (at the same port as the server's, wjich +defaults to 9440). + +The Windows machine uses freeSSHd (not a `bash'-based SSH server like +Cygwin) and communicates back to the server as "10.0.0.1" instead of +using an SSH tunnel. To make that work, `#:server-hosts' is specified +as the empty list to make the server listen on all interfaces (instead +of just "localhost") --- which is possibly less secure than the +default restriction that allows build-server connections only via +"localhost". With this configuration file in "site.rkt",