Aqua Phoenix
     >>  References >>  Operating Systems  


1.11 SunRay Server Setup

This section is in reference to the Perl Script for connecting a SunRay thin client to a SunRay server in a shared, routed environment. For more details on this topic, visit the Software/SunRay section .

The setup of a SunRay server in a shared, routed environment is unique in that it shares the network interface of the server (i.e. it is not dedicated to SunRay alone), and it must be able to serve SunRay thin clients on any external network (i.e. one on a different subnet). The SunRay setup scripts facilitate this scenario by setting up a DHCP server for the external subnet. However, problems typically occur with the shared interface or IP address, expecially if the IP address is dynamically assigned to the machine hosting the SunRay server, for example when using DSL and a PPP interface (sppp, sppp0). It is not unusual or unexpected for the setup script utconfig to throw error messages of type "Error: unable to get information on primary interface", "Error: cannot set firmware version to network macro "IP_ADDRESS"", "Error: cannot set firmware version to network macro "IP_ADDRESS"", etc. The reason behind these error messages can be found when analyzing the setup scripts. A sequence of calls to examine the running network interface and comparisons to routing tables invalidate the expected results.

Below is the procedure for setting up a SunRay Server for a shared, routed environment. These instructions have been tested on SunRay versions 2.0 and 3.1 (srss_2, srss_31). I ran into many unique problems on the server I am using (a Sun Blade 1000):

  • The server is connected at home to the net over DSL (network interface eri [eri0] masked by PPP interface sppp [sppp0])
  • A dynamic IP address is used for this machine
  • An internal network is served by the server over a separate quad network card (interface qfe [qfe0])
  • The internal network is firewalled and routed network. This means IPNAT (network address translation) is performed in addition to PFIL (packet filtering).
  • The SunRay thin client is located on a completely different subnet at the University

1.11.1 Adding the package to your system

This step is independent of configuration. Unzip or, find the script utinstall and:


1.11.2 DHCP Server Setup

The DHCP server is necessary for serving IP addresses for the SunRay thin client. In a shared, routed environment these addresses are not part of the SunRay server's subnet. Instead, you will need to figure out what address block can be used on the subnet where the thin client(s) reside. This may be one IP address, but it could be a block of addresses much larger. Bottom line: if you have one SunRay thin client and expect to assign a static IP address to it, you will need the DHCP server to serve that address. If you have multiple SunRay thin clients, and/or expect to serve one of many IP addresses to your thin clients, then the DHCP server will need to serve those addresses to the thin client(s). In any case, you need the DHCP server.

The DHCP server may already be running on your SunRay Server. To check whether it is, or is misconfigured, or is not running at all, type:

This is a GUI interface, not command line. One of four things can happen:

  1. The DHCP server is not configured at all, and a window pops up asking whether to configure as a DHCP server or a BOOTP server. Select DHCP and continue. During the configuration later, this DHCP server will be configured automatically. Once the main menu pops up, exit the application. There is no need to customize it.
  2. The DHCP server is already selected - a window with a DHCP table pops up, which is likely empty. There is no need to customize at this point. Exit the application.
  3. The BOOTP server is already configured. You'll have to figure out whether it is running intentionally. If not, you will want to unconfigure it. From the menu line select " Service", then "Unconfigure". After confirming, the application will close. Start it up again and follow instructions in point 1.
  4. The command doesn't work - the DHCP server software is not installed. You will need to find the package, install it, then follow instructions from point 1.

1.11.3 Configure the SunRay Server for the shared, routed network

cd /opt/SUNWut/sbin
From here, you will emerge into a set of questions regarding IP addresses, etc. Before following through the setup script, ensure the correct values for:

  • The subnet which hosts the SunRay thin clients (likely different from the one your server is on, otherwise you wouldn't be reading this tutorial). Example:
  • The Authentication Server (likely the same as your SunRay server). Example:
  • The Firmware Server (likely same as SunRay server)
  • IP address of block of IP addresses served by DHCP to the thin client. Example: -
  • The router for the subnet serving the thin client. Example:

Without paying attention to the SunRay Server's network setup, you may as well attempt to run the configuration tool ( utadm).

./utadm -A
Example output:

### Configuring /etc/nsswitch.conf
### Configuring Service information for Sun Ray
### Disabling Routing
  Selected values for subnetwork ""
    net mask:
    no IP addresses offered
    auth server list:
    firmware server:
  Accept as is? ([Y]/N): N
  netmask: (cannot be changed - system defined netmask)
  Do you want to offer IP addresses for this subnet? (Y/[N]): Y
  new first Sun Ray address: []
  number of Sun Ray addresses to allocate: [0] 10
  auth server list:
To read auth server list from file, enter file name:
Auth server IP address (enter to end list):
If no server in the auth server list responds,
should an auth server be located by broadcasting on the network? ([Y]/N): N
  new firmware server: []
  new router: []
  Selected values for subnetwork ""
    net mask:
    first unit address:
    last unit address:
    auth server list:
    firmware server:
  Accept as is? ([Y]/N): Y
Error: unable to get information on primary interface
Error:  unable to get information on the primary interface.
### Configuring firmware version for Sun Ray
Error: cannot set firmware version to network macro "":
Configuration for DHCP subnet does not exist.
### Configuring Sun Ray Logging Functions
While the configuration parameters (IP addresses, etc.) may be correct, the setup fails due to problems with the primary interface. Especially on a SunRay Server where network interfaces are masked, replaced by PPP, used for other things, etc., these problems are inevitable.

One of the tests done during configuration with utadm -A, which is specifically targeted at setting up a subnet, is an inspection of network configuration files and routing tables. Specifically, the following tests are performed:

Test 1 (do not execute as presented here): Find hostname of the SunRay Server (e.g. the donald in in network configuration files (/etc/hostname.*, where * denotes the interface name, e.g. eri0, hme0, qfe0, sppp0, etc.) The following line greps for the hostname, and retains the interface for which the hostname appears:

typeset intf_list=`grep -l "^${HOSTNAME}\$" ${HOSTNAME_R}.* | sed -e "s/^..*\.\([^\.][^\.]*\)$/\1/"`
Test 2 (do not execute as presented here): Once the hostname's interface is determined, the following line determines the IP address for the hostname from the routing tables:

netstat -n -I ${intf} -f inet
If the first command fails, e.g. when the hostname isn't found in the configuration files, the second command fails as well. If the incorrect interface has been attributed to the hostname, then certainly the routing tables will return an incorrect value, and the second command fails.

Based on the results of the output, the script will continue successfully or exit. Generally, you should perform these tests manually to determine where the problem lies. That is:

Test 0 (execute as presented here): Determine your SunRay Server's hostname:

Test 1 (execute as presented here): Find the hostname in the network configuration files (/etc/hostname.*):

grep HOSTNAME /etc/hostname.*
where HOSTNAME is the result from the previous command.

If it is found, continue to the next test. If not, you'll find a solution below.

Test 2 (execute as presented here)Determine the IP address for the interface for which the hostname has been configured, either by using the result from the previous command, or by inspecting each /etc/hostname.* file individually, you will be able to determine the interface. Once you found the * (INTERFACE):

netstat -n -I INTERFACE -f inet
where INTERFACE is the interface (eri0, hme0, qfe0, etc.)

If it is found, then you shouldn't see the errors above in the first place. Otherwise, find the solution below.

These commands fail, not necessarily because the system has been incorrectly configured. There may be many reasons for why the hostname does not appear in an /etc/hostname.* file. Especially when IP addresses are dynamically allocated, the hostname may not be written to an /etc/hostname.* file during an automatic network configuration. Also, when using a PPP interface (e.g. sppp) which masks the physical interface (e.g. eri), an /etc/hostname.sppp0 file is not necessarily generated during DSL negotiations. Regardless of static or dynamic IP allocation, a machine will be assigned a hostname. This hostname can be thought of a reference to the network interface, which again references the IP address. These links will need to be established in files in order to successfully complete the setup.

Just for the purpose of completing the setup using the utadm script, the following change in configuration will be done temporarily and reverted after setup:

  • If only step 2 above failed, then the INTERFACE in the filename /etc/hostname.INTERFACE has been incorrectly assigned. Rename the file to reflect the correct INTERFACE. One way to determine this is to type netstat -rn and to find the correct IP address for the server, and then read off the interface which is served by this IP address.

    This scenario may occur when interfaces are masked, e.g. in the case of PPP dialup. While the physical interface may be (eri0, hme0, etc.), the virtual interface hosting the IP address is (sppp0, etc.).

    Example: /etc/hostname.eri0 contains the hostname donald. After PPP dialup, eri0 is masked by sppp0, and hence the correct link between IP address and hostname is the interface sppp0, and not eri0. The previous file should be renamed to hostname.sppp0

  • If both above steps failed, then /etc/hostname.INTERFACE does not exist in the first place, or contains an incorrect value altogether. Again, determine the interface serving the IP address ( netstat -rn dumps a table with IP addresses and their associated interfaces), then create the file /etc/hostname.INTERFACE and insert the correct hostname (from hostname ). After running the above two test commands, the server's IP address should be resolved correctly.

    This scenario may occur when the host's IP address is dynamically allocated, and no /etc/hostname.INTERFACE is generated.

After this temporary configuration modification, re-run the setup command, which should now complete successfully.

./utadm -A
Finally, revert to the original configuration.

1.11.4 Configuration of Sun Ray server Software

In this step, the server software is prepared to serve the thin clients:

If Sun Ray Web Administration is desired, be sure to have the Apache Web Server installed. The setup script seeks Apache only in directory /usr/apache. If Apache is located elsewhere, you will need to migrate the hereby generated Apache configuration files manually. I suggest: Install the Apache packages (SUNWaclg, SUNWapchr, SUNWapchu) just for delivering to SunRay. Any separate Apache web server should be installed elsewhere (should be using Apache2 anyway), and likely it will not conflict since SunRay's web server can be set to a high port number, whereas a typical real web server runs on port 80.

cd /opt/SUNWut/sbin

Configuration of Sun Ray server Software

This script automates the configuration of the Sun Ray server software
and related software products.  Before proceeding, you should have read
the Sun Ray server 3.1 Installation Guide and filled out the
Configuration Worksheet.  This script will prompt you for the values
you filled out on the Worksheet.  For your convenience, default values
(where applicable) are shown in brackets.

Continue ([y]/n)? y
Enter Sun Ray admin password:
Re-enter Sun Ray admin password:

Configure Sun Ray Web Administration? ([y]/n)? y

An installation of Apache Web Server version  1.3 has been
detected at /etc/apache.  This script can configure
the Apache server on this server for you.

Warning: if you choose to configure Apache, the existing
Apache configuration file will be over-written.  If this server
is presently configured as a Webserver and you want to preserve
your current configuration, you must answer "NO" and merge the
configuration file manually by following the instructions in the
Administration Guide on how to configure the Apache server.

Would you like to configure this
server to host the Sun Ray Web Administration? ([y]/n)? y
Enter port number [1660]:
Enter CGI username [utwww]:
Enable remote server administration? (y/[n])? n

Configure Controlled Access Mode? (y/[n])? n

Configure this server for a failover group? (y/[n])? n

About to configure the following software products:

Sun Ray Data Store 2.1
    Hostname: donald
    Sun Ray root entry: o=utdata
    Sun Ray root name: utdata
    Sun Ray utdata admin password: (not shown)
    SRDS 'rootdn': cn=admin,o=utdata

Apache Web Server 1.3
    Apache Web Server port number: 1660
    Remote server administration: no
    CGI username: utwww

Sun Ray server 3.1
    Failover group: no
    Controlled Access Mode: no

Continue ([y]/n)? y

Updating Sun Ray Data Store schema ...

Updating Sun Ray Data Store ACL's ...

Creating Sun Ray Data Store Datastore ...

Restarting Sun Ray Data Store ...
Starting Sun Ray Data Store daemon .
Tue Jun 13 23:27 : utdsd starting

Loading Sun Ray Data Store ...

Executing '/usr/bin/ldapadd -p 7012 -D cn=admin,o=utdata' ...
adding new entry o=utdata

adding new entry o=v1,o=utdata

adding new entry utname=donald,o=v1,o=utdata

adding new entry utname=desktops,utname=donald,o=v1,o=utdata

adding new entry utname=users,utname=donald,o=v1,o=utdata

adding new entry utname=logicalTokens,utname=donald,o=v1,o=utdata

adding new entry utname=rawTokens,utname=donald,o=v1,o=utdata

adding new entry utname=multihead,utname=donald,o=v1,o=utdata

adding new entry utname=container,utname=donald,o=v1,o=utdata

adding new entry utname=properties,utname=donald,o=v1,o=utdata

adding new entry cn=utadmin,utname=donald,o=v1,o=utdata

adding new entry utname=smartCards,utname=donald,o=v1,o=utdata

adding new entry utordername=probeorder,utname=smartCards,utname=donald,o=v1,o=utdata

adding new entry utname=policy,utname=donald,o=v1,o=utdata

adding new entry utname=resDefs,utname=donald,o=v1,o=utdata

adding new entry utname=prefs,utname=donald,o=v1,o=utdata

adding new entry utPrefType=resolution,utname=prefs,utname=donald,o=v1,o=utdata

adding new entry utPrefClass=advisory,utPrefType=resolution,utname=prefs,utname=donald,o=v1,o=utdata

Added 18 new LDAP entries.

Creating Sun Ray server Configuration ...
Adding user account for 'utwww' (ut admin web server cgi user) ...
/usr/apache/bin/apachectl restart: httpd not running, trying to start
/usr/apache/bin/apachectl restart: httpd started

Unique "/etc/opt/SUNWut/gmSignature" has been generated.

Restarting Sun Ray Data Store ...
Stopping Sun Ray Data Store daemon
.Sun Ray Data Store daemon stopped
Starting Sun Ray Data Store daemon .
Tue Jun 13 23:27 : utdsd starting
Adding user admin ...
User(s) added successfully!

The current policy has been modified.  You must restart the
authentication manager to activate the changes.

Configuration of Sun Ray server has completed.  Please check
the log file, /var/adm/log/utconfig.2006_06_13_23:26:39.log, for errors.

1.11.5 Other useful notes TCP Routing conflicting with SunRay Server

When IP forwarding is enabled on the SunRay Server prior to installation, for example to serve an internal network through the host, then forwarding will be disabled during utadm configuration. Check before running utadm:

ndd -get /dev/tcp ip_forwarding
results in either 0 (no forwarding) or 1 (forwarding)

Necessarily after running utadm, which explicitely logs "Disabling Routing", IP forwarding will be disabled. Re-enable it if necessary:

ndd -set /dev/tcp ip_forwarding 1 Dynamic IP changes and SunRay Server

When the IP of the host changes, either due to reboot or reconnecting to the network, the above configuration will necessarily be invalidated. There is no need to re-configure the server. A restart of the SunRay Server will suffice: