Document ID: ID22076
Synopsis: How to permanently set the Sun Ray[TM] screen resolution

Keyword(s):Sun Ray, SunRay, utresadm, utxconfig, utsettings, utset, resolution, screen resolution

On a Sun Ray[TM] appliance, how can I set the default screen resolution to
a value which persists after logouts, hot desking, and powercycle events?
On the SRSS 2.0, either utresadm or utxconfig can be used to define
persistent screen resolution settings. On the SRSS 1.3 and earlier, only
utxconfig is available. Is is recomended that before you configure
persistent screen resolutions, that the Sun Ray server is configured, i.e.,
that utconfig has been run. 


How to use utresadm to define persistent screen resolution settings:
====================================================================
IMPORTANT NOTE: In the SRSS 2.0 implementation, utresadm settings 
  changes might become active only after a restart of services,
  which will end all user sessions. See RFE 4969150 for details.

- As system administrator, set the desired resolution using
  /opt/SUNWut/sbin/utresadm. Only resolutions available through
  /opt/SUNWut/sbin/utresdef are allowed.
- utresadm settings are active only when autosizing is enabled.
  Hence, you must enable autosizing, using
     "/opt/SUNWut/bin/utxconfig [-a] -s on [-t <token>]".
  The "-a" option changes settings for the default token.
  Without the "-a" option, settings for specific tokens can be changed. 
- Among conflicting settings, the more specific utresadm setting will
  prevail. I.e., any appliance specific utresadm setting overrules any   
  utresadm settings made for the default token. The appliance specific
  setting can, in turn, be overruled for a specific token in
  combination with the same appliance by specifying the token 
  in the "-t <token>" option rather than "-t default".
- utresadm allows defining both screen resolution and refresh rate.


To set a default resolution for a specific appliance for all tokens,
use the "-t default" option:

# /opt/SUNWut/sbin/utresadm -a -c default -t default <resolution>
would set the overall default resolution ("-c default").

# /opt/SUNWut/sbin/utresadm -a -c IEEE802.080020f84a86 -t default
1280x1024@76
sets a default resolution of 1280x1024@76 for the appliance with MAC
address 080020f84a86, for all tokens which have auto sizing enabled.


A detailed example how to use utresadm:
---------------------------------------
See IMPORTANT NOTE at the beginning of this section.

# /opt/SUNWut/sbin/utresadm -o
# 
(there is nothing specified thus far)
# /opt/SUNWut/sbin/utresadm -a -c IEEE802.0003ba141958 -t default
1152x900@76

Then the user inserted a smartcard, and logged in. As this was a new
user session, the user got the new utresadm settings for the desktop
dimensions:
% /opt/SUNWut/sbin/utresadm
IEEE802.0003ba141958  default                         --     1152x900@76

As autosizing is enabled, the utxconfig resolution does not apply here:
% /opt/SUNWut/bin/utxconfig -l
RESOLUTION=1280x1024   <---- ignored because autosizing enabled
ENABLE_PSEUDOCOLOR_VISUAL=no
DEFAULT_PSEUDOCOLOR_VISUAL=no
ENABLE_AUTO_SIZING=yes <---- autosizing enabled
ENABLE_MULTISCREEN=yes
ENABLE_XINERAMA=no
SCREEN_GEOMETRY=1x1    <---- ignored because autosizing enabled
SCREEN_ORDER=0
Hence, the display is indeed running at the 1152x900@76 configured by
utresadm.

With all utresadm configurations, the appliance should also pick up the
resolution defined with utresadm. When a new session has been started,
both the Xsun and the framebuffer resolution initially will be identical
to the one set with utresadm. Especially, utresadm does not check whether
the monitor attached to the appliance supports the resolution configured
with utresadm. Thus, if you use utresadm to configure a screen resolution
for a Sun Ray 150 appliance which differs from the 150's fixed 1024x768
resolution, the user will get a black border resp. the paning effect.


To enter multiple utresadm configurations at once, use the "utresadm -i"
option. It reads from stdin, but you can use a pipe to use a file as input
into utresadm.

Example for utresadm -i:
------------------------

# /opt/SUNWut/sbin/utresadm -o > utresadm.out (create example data file)

# cat utresadm.out
# Resolution export version=1 hostname=labhost

# Resolution export started at 2003-06-18T13:00:0Z
cid=IEEE802.0003ba141958 token=default res=1152x900@76 
cid=IEEE802.0003ba141958 token=MicroPayflex.5000f8ad00130100
res=1024x768@75 
# Resolution export ended at 2003-06-18T13:00:0Z

# /opt/SUNWut/sbin/utresadm -i < utresadm.out
cid=IEEE802.0003ba141958 token=default: Data already exists
cid=IEEE802.0003ba141958 token=MicroPayflex.5000f8ad00130100: Data already
exists

Here, both already exist, and thus are ignored. You can delete them
# /opt/SUNWut/sbin/utresadm -d -c IEEE802.0003ba141958 -t
MicroPayflex.5000f8ad00130100
# /opt/SUNWut/sbin/utresadm -d -c IEEE802.0003ba141958 -t default
# /opt/SUNWut/sbin/utresadm -o
#
and then re-add them using utresadm -i 
# /opt/SUNWut/sbin/utresadm -i < utresadm.out
IEEE802.0003ba14195   default                         --     1152x900@76
IEEE802.0003ba141958  MicroPayflex.5000f8ad00130100   --     1024x768@75
# /opt/SUNWut/sbin/utresadm -o
# Resolution export version=1 hostname=labhost
# Resolution export started at 2003-06-18T13:02:0Z
cid=IEEE802.0003ba141958 token=default res=1152x900@76 
cid=IEEE802.0003ba141958 token=MicroPayflex.5000f8ad00130100
res=1024x768@75 
# Resolution export ended at 2003-06-18T13:02:0Z
# 

A non-prileged user cannot run utresadm -a/-i, but he can overrule 
the settings for his own token using utxconfig.



How to use utxconfig to define persistent screen resolution settings:
=====================================================================

- Once logged in, run 
     % /opt/SUNWut/bin/utxconfig -s off -r <resolution>
  such as
     % /opt/SUNWut/bin/utxconfig -s off -r 1280x1024
     Xconfig record added/changed.
  This will disable autosizing for the current token, thus
  disabling utresadm resolution settings.
- Then log out and log in again, and confirm with "utxconfig -l":
  % /opt/SUNWut/bin/utxconfig -l
  RESOLUTION=1280x1024
  ENABLE_PSEUDOCOLOR_VISUAL=no
  DEFAULT_PSEUDOCOLOR_VISUAL=no
  ENABLE_AUTO_SIZING=no  <---- autosizing disabled, 1280x1024 is active
  ENABLE_MULTISCREEN=no
  ENABLE_XINERAMA=no
  SCREEN_GEOMETRY=1x1
  SCREEN_ORDER=0
- The root user can use "utxconfig -a" to set global defaults, and can
  change settings for any token using the "-t <token>" option. 
- utxconfig can not change the refresh rate, and utxconfig settings 
  without the "-a" option apply for a specific token. 
  I.e., utxconfig settings for a smartcard token will apply 
  regardless of the appliance at which the session is created.
- when utxconfig settings are used, the Sun Ray appliance will still
  use DDC to check for resolutions supported by the monitor.


To delete the utxconfig settings again, use "utxconfig -e [-t <token>]".
Finally, "utxconfig -o" allows seeing the utxconfig configurations for all
tokens. Only resolutions where autosizing is disabled currently apply:
# utxconfig -o
user.1055330985-7666,1280x1024,-1,no,no,yes,yes,no,1,1,0 <--- enabled
user.1055332426-6402,1280x1024,-1,no,no,no,yes,no,1,1,0  <--- disabled
MicroPayflex.00004acf65000100,1280x1024,-1,no,no,yes,yes,no,1,1,0.
                                                 ^^^     <--- enabled
Here, only the 1280x1024 for user.1055332426-6402 applies. The utxconfig
resolutions set for user.1055330985-7666 and MicroPayflex.00004acf65000100
are ignored.



Special considerations on multihead displays:
=============================================

The multihead implementation in the SRSS 2.0 and earlier does not allow
independent screen resolutions for multihead secondary screens. If
autosizing is enabled, the secondary will pick up the resolution of the
primary screen. If autosizing is disabled, and utxconfig is used to define
persistent screen resolutions, then
   - ENABLE_MULTISCREEN must be set to "yes"
and
   - the SCREEN_GEOMETRY must be set to the size of the multihead group 
     (with the -R option)
With a misconfiguration of the screen geometry, secondary screens will
show a dark purple screen (SRSS 1.2, and SRSS 1.3), resp. a black screen
(SRSS 2.0).


Example correct multihead configuration:
----------------------------------------
# /opt/SUNWut/bin/utxconfig -t MicroPayflex.5000f8b000130100 -m on -s off
-r 800x600 -x off -R 2x1 
(logout and login)
% /opt/SUNWut/bin/utxconfig -l
RESOLUTION=800x600
ENABLE_PSEUDOCOLOR_VISUAL=no
DEFAULT_PSEUDOCOLOR_VISUAL=no
ENABLE_AUTO_SIZING=no  <--- autosizing disabled, thus RESOLUTION is active
ENABLE_MULTISCREEN=yes <--- multiscreen enabled
ENABLE_XINERAMA=no     <--- "utxconfig -x off" disables xinerama
SCREEN_GEOMETRY=2x1    <--- screen geometry is set to two columns, one row
SCREEN_ORDER=0         <--- optional


Abbreviations:
==============
SRSS: Sun Ray[TM] Server Software.


References:
===========
utxconfig(1)
utresadm(1)
On Sun Ray[TM], there are two independent screen resolutions, the
resolution used by the Xsun process, also called "virtual resolution",
resp. the "desktop dimensions", and the resolution used by the framebuffer
in the appliance, also called the "physical resolution". To set
persistent screen resolutions on Sun Ray[TM], the desktop dimensions must
be configured. The desktop dimensions are fixed for the duration of a
session, as the Xsun process cannot dynamically change the resolution it
uses.

Upon Sun Ray[TM] session startup, the desktop dimensions are computed as
follows:

1.) Check whether autosizing is enabled for the current token.

2.) If autosizing is disabled, the settings from utxconfig are used.
    The settings from utxconfig also are used with the SRSS 1.1 and 
    the SRSS 1.0, which do not provide the autosizing feature.

3.) If autosizing is enabled, then with the SRSS 2.0 utresadm screen
    resolution settings will be evaluated first. With the SRSS 1.2 and
    the SRSS 1.3, and also with the SRSS 2.0 if no applicable utresadm 
    settings are detected, the Sun Ray[TM] appliance will use a DDC/EDID   
    request to identify the monitor's supported resolutions. If the 
    DDC/EDID fails, then the system-wide fallback resolution will be used,
    which is 1152x900 for the SRSS 1.x, and the VGA 640x480 for the 
    SRSS 2.0.