1XSM(1)                      General Commands Manual                     XSM(1)
2
3
4

NAME

6       xsm - X Session Manager
7

SYNOPSIS

9       xsm [-display display] [-session sessionName] [-verbose]
10

DESCRIPTION

12       xsm  is  a session manager.  A session is a group of applications, each
13       of which has a particular state.  xsm allows you  to  create  arbitrary
14       sessions  -  for example, you might have a "light" session, a "develop‐
15       ment" session, or an "xterminal" session.  Each session  can  have  its
16       own  set  of applications.  Within a session, you can perform a "check‐
17       point" to save application state, or a "shutdown"  to  save  state  and
18       exit  the  session.  When you log back in to the system, you can load a
19       specific session, and you can delete sessions you  no  longer  want  to
20       keep.
21
22       Some  session  managers  simply allow you to manually specify a list of
23       applications to be started in a session.  xsm is more powerful  because
24       it lets you run applications and have them automatically become part of
25       the session.  On a simple level, xsm is useful  because  it  gives  you
26       this ability to easily define which applications are in a session.  The
27       true power of xsm, however, can be taken advantage  of  when  more  and
28       more applications learn to save and restore their state.
29

OPTIONS

31       -display display
32               Causes xsm to connect to the specified X display.
33
34       -session sessionName
35               Causes xsm to load the specified session, bypassing the session
36               menu.
37
38       -verbose
39               Turns on debugging information.
40

SETUP

42   .xsession file
43       Using xsm requires a change to your .xsession file:
44
45       The last program executed by your .xsession file should be  xsm.   With
46       this  configuration,  when  the  user  chooses to shut down the session
47       using xsm, the session will truly be over.
48
49       Since the goal of the session manager is to restart clients  when  log‐
50       ging  into  a  session,  your  .xsession  file,  in general, should not
51       directly start up applications.  Rather,  the  applications  should  be
52       started  within  a  session.  When xsm shuts down the session, xsm will
53       know to restart these applications.  Note however that there  are  some
54       types  of applications that are not "session aware".  xsm allows you to
55       manually add these applications to your session (see the section titled
56       Client List).
57
58   SM_SAVE_DIR environment variable
59       If  the  SM_SAVE_DIR environment variable is defined, xsm will save all
60       configuration files in this directory.  Otherwise, they will be  stored
61       in  the  user's  home  directory.   Session aware applications are also
62       encouraged to save their checkpoint files in the SM_SAVE_DIR directory,
63       although the user should not depend on this convention.
64
65   Default Startup Applications
66       The  first time xsm is started, it will need to locate a list of appli‐
67       cations to start up.  For example, this list  might  include  a  window
68       manager, a session management proxy, and an xterm.  xsm will first look
69       for the file .xsmstartup in the user's home directory.   If  that  file
70       does not exist, it will look for the system.xsm file that was set up at
71       installation time.  Note that xsm provides a "fail  safe"  option  when
72       the  user  chooses  a session to start up.  The fail safe option simply
73       loads the default applications described above.
74
75       Each line in the startup file should contain  a  command  to  start  an
76       application.  A sample startup file might look this:
77
78       <start of file>
79       twm
80       smproxy
81       xterm
82       <end of file>
83

STARTING A SESSION

85       When xsm starts up, it first checks to see if the user previously saved
86       any sessions.  If no saved sessions exist,  xsm  starts  up  a  set  of
87       default  applications (as described above in the section titled Default
88       Startup Applications).  If at least one session exists, a session  menu
89       is  presented.   The  -session  option forces the specified sessionName
90       session to be loaded, bypassing the session menu.
91
92   The session menu
93       The session menu presents the user with a list of  sessions  to  choose
94       from.   The  user  can  change  the currently selected session with the
95       mouse, or by using the up and down arrows on the keyboard.   Note  that
96       sessions which are locked (i.e. running on a different display) can not
97       be loaded or deleted.
98
99       The following operations can be performed from the session menu:
100
101       Load Session          Pressing this  button  will  load  the  currently
102                             selected  session.   Alternatively,  hitting  the
103                             Return key will also load the currently  selected
104                             session,  or  the user can double click a session
105                             from the list.
106
107       Delete Session        This operation will delete the currently selected
108                             session, along with all of the application check‐
109                             point files associated with the  session.   After
110                             pressing  this  button, the user will be asked to
111                             press the button a second time in order  to  con‐
112                             firm the operation.
113
114       Default/Fail Safe     xsm  will  start up a set of default applications
115                             (as described above in the section titled Default
116                             Startup  Applications).   This is useful when the
117                             user wants to start a fresh session,  or  if  the
118                             session  configuration  files  were corrupted and
119                             the user wants a "fail safe" session.
120
121       Cancel                Pressing this button will cause xsm to exit.   It
122                             can  also  be  used  to cancel a "Delete Session"
123                             operation.
124

CONTROLLING A SESSION

126       After xsm determines which session to load, it brings up its main  win‐
127       dow, then starts up all applications that are part of the session.  The
128       title bar for the session manager's main window will contain  the  name
129       of the session that was loaded.
130
131       The following options are available from xsm's main window:
132
133       Client List       Pressing  this button brings up a window containing a
134                         list of all clients that are in the current  session.
135                         For  each client, the host machine that the client is
136                         running on is presented.  As clients  are  added  and
137                         removed  from  the  session,  this list is updated to
138                         reflect the changes.  The user is able to control how
139                         these clients are restarted (see below).
140
141                         By  pressing the View Properties button, the user can
142                         view the  session  management  properties  associated
143                         with the currently selected client.
144
145                         By  pressing  the  Clone button, the user can start a
146                         copy of the selected application.
147
148                         By pressing the Kill  Client  button,  the  user  can
149                         remove a client from the session.
150
151                         By  selecting  a  restart  hint from the Restart Hint
152                         menu, the  user  can  control  the  restarting  of  a
153                         client.  The following hints are available:
154
155                         -  The  Restart  If  Running  hint indicates that the
156                         client should be restarted in the next session if  it
157                         is connected to the session manager at the end of the
158                         current session.
159
160                         - The Restart Anyway hint indicates that  the  client
161                         should  be  restarted  in the next session even if it
162                         exits before the current session is terminated.
163
164                         - The Restart Immediately  hint  is  similar  to  the
165                         Restart  Anyway  hint, but in addition, the client is
166                         meant to run continuously.  If the client exits,  the
167                         session manager will try to restart it in the current
168                         session.
169
170                         - The Restart Never hint indicates  that  the  client
171                         should not be restarted in the next session.
172
173                         Note  that  all  X  applications  may not be "session
174                         aware".  Applications that are not session aware  are
175                         ones  that  do  not  support the X Session Management
176                         Protocol or they can not be detected by  the  Session
177                         Management  Proxy (see the section titled THE PROXY).
178                         xsm allows the user to manually add such applications
179                         to the session.  The bottom of the Client List window
180                         contains a text entry field in which application com‐
181                         mands can be typed in.  Each command should go on its
182                         own line.  This information will be  saved  with  the
183                         session  at  checkpoint  or  shutdown time.  When the
184                         session is restarted, xsm will restart these applica‐
185                         tions  in  addition  to  the  regular "session aware"
186                         applications.
187
188                         Pressing the Done button removes the Client List win‐
189                         dow.
190
191       Session Log...    The  Session  Log  window presents useful information
192                         about the session.  For example, when  a  session  is
193                         restarted,  all  of the restart commands will be dis‐
194                         played in the log window.
195
196       Checkpoint        By performing a checkpoint, all applications that are
197                         in  the  session  are asked to save their state.  Not
198                         every application will save its complete  state,  but
199                         at  a minimum, the session manager is guaranteed that
200                         it will receive the command required to  restart  the
201                         application (along with all command line options).  A
202                         window manager participating in  the  session  should
203                         guarantee  that  the  applications  will come back up
204                         with the same window configurations.
205
206                         If the session being checkpointed was never  assigned
207                         a  name,  the user will be required to specify a ses‐
208                         sion name.   Otherwise,  the  user  can  perform  the
209                         checkpoint  using  the current session name, or a new
210                         session name can be specified.  If the  session  name
211                         specified  already exists, the user will be given the
212                         opportunity to specify a different name or  to  over‐
213                         write the already existing session.  Note that a ses‐
214                         sion which is locked can not be overwritten.
215
216                         When performing a checkpoint, the user must specify a
217                         Save  Type which informs the applications in the ses‐
218                         sion how much state they should save.
219
220                         The Local type indicates that the application  should
221                         save  enough information to restore the state as seen
222                         by the user.  It should not affect the state as  seen
223                         by  other users.  For example, an editor would create
224                         a temporary file containing the contents of its edit‐
225                         ing buffer, the location of the cursor, etc...
226
227                         The Global type indicates that the application should
228                         commit all of its data to permanent, globally  acces‐
229                         sible  storage.  For example, the editor would simply
230                         save the edited file.
231
232                         The Both type indicates that the  application  should
233                         do both of these.  For example, the editor would save
234                         the edited file, then create a  temporary  file  with
235                         information  such  as  the  location  of  the cursor,
236                         etc...
237
238                         In addition to the Save Type, the user  must  specify
239                         an Interact Style.
240
241                         The  None  type indicates that the application should
242                         not interact with the user while saving state.
243
244                         The Errors type indicates that  the  application  may
245                         interact  with  the  user  only if an error condition
246                         arises.
247
248                         The Any  type  indicates  that  the  application  may
249                         interact  with  the  user for any purpose.  Note that
250                         xsm will only allow one application to interact  with
251                         the user at a time.
252
253
254                         After  the checkpoint is completed, xsm will, if nec‐
255                         essary, display  a  window  containing  the  list  of
256                         applications  which  did not report a successful save
257                         of state.
258
259       Shutdown          A shutdown provides all of the  options  found  in  a
260                         checkpoint, but in addition, can cause the session to
261                         exit.  Note that if the interaction style  is  Errors
262                         or  Any,  the user may cancel the shutdown.  The user
263                         may also cancel the shutdown if any of  the  applica‐
264                         tions report an unsuccessful save of state.
265
266                         The  user may choose to shutdown the session with our
267                         without performing a checkpoint.
268

HOW XSM RESPONDS TO SIGNALS

270       xsm will respond to a SIGTERM signal by performing a shutdown with  the
271       following  options: fast, no interaction, save type local.  This allows
272       the user's session to be saved when the system is being  shutdown.   It
273       can also be used to perform a remote shutdown of a session.
274
275       xsm  will  respond  to a SIGUSR1 signal by performing a checkpoint with
276       the following options: no interaction, save type  local.   This  signal
277       can be used to perform a remote checkpoint of a session.
278

THE PROXY

280       Since  not  all  applications have been ported to support the X Session
281       Management Protocol, a proxy service exists to allow "old"  clients  to
282       work  with  the  session  manager.  In order for the proxy to detect an
283       application joining a session, one of the following must be true:
284
285       -  The  application  maps   a   top   level   window   containing   the
286       WM_CLIENT_LEADER  property.   This  property  provides a pointer to the
287       client leader window which contains the WM_CLASS, WM_NAME,  WM_COMMAND,
288       and WM_CLIENT_MACHINE properties.
289
290       or ...
291
292       -  The  application  maps a top level window which does not contain the
293       WM_CLIENT_LEADER property.  However, this top level window contains the
294       WM_CLASS, WM_NAME, WM_COMMAND, and WM_CLIENT_MACHINE properties.
295
296       An  application that support the WM_SAVE_YOURSELF protocol will receive
297       a WM_SAVE_YOURSELF client message each time the session manager  issues
298       a  checkpoint  or shutdown.  This allows the application to save state.
299       If an application does not support the WM_SAVE_YOURSELF protocol,  then
300       the  proxy  will  provide  enough information to the session manager to
301       restart the application  (using  WM_COMMAND),  but  no  state  will  be
302       restored.
303

REMOTE APPLICATIONS

305       xsm  requires  a remote execution protocol in order to restart applica‐
306       tions on remote machines.  Currently, xsm supports the rstart protocol.
307       In  order to restart an application on remote machine X, machine X must
308       have rstart installed.  In the future, additional remote execution pro‐
309       tocols may be supported.
310

SEE ALSO

312       smproxy(1), rstart(1)
313

AUTHORS

315       Ralph Mor, X Consortium
316       Jordan Brown, Quarterdeck Office Systems
317
318
319
320X Version 11                       xsm 1.0.4                            XSM(1)
Impressum