Table of Contents

Abstract

This document specifies a protocol that facilitates the management of groups of client applications by a session manager. The session manager can cause clients to save their state, to shut down, and to be restarted into a previously saved state. This protocol is layered on top of the X.Org ICE protocol.

Definitions and Goals

The purpose of the X Session Management Protocol (XSMP) is to provide a uniform mechanism for users to save and restore their sessions. A session is a group of clients, each of which has a particular state. The session is controlled by a network service called the session manager. The session manager issues commands to its clients on behalf of the user. These commands may cause clients to save their state or to terminate. It is expected that the client will save its state in such a way that the client can be restarted at a later time and resume its operation as if it had never been terminated. A client's state might include information about the file currently being edited, the current position of the insertion point within the file, or the start of an uncommitted transaction. The means by which clients are restarted is unspecified by this protocol.

For purposes of this protocol, a client of the session manager is defined as a connection to the session manager. A client is typically, though not necessarily, a process running an application program connected to an X Window System display. However, a client may be connected to more than one X display or not be connected to any X displays at all.

This protocol is layered on top of the X Consortium's ICE protocol and relies on the ICE protocol to handle connection management and authentication.

Overview of the Protocol

Clients use XSMP to register themselves with the session manager (SM). When a client starts up, it should connect to the SM. The client should remain connected for as long as it runs. A client may resign from the session by issuing the proper protocol messages before disconnecting. Termination of the connection with-out notice will be taken as an indication that the client died unexpectedly.

Clients are expected to save their state in such a way as to allow multiple instantiations of themselves to be managed independently. A unique value called a client-ID is provided by the protocol for the purpose of disambiguating multiple instantiations of clients. Clients may use this ID, for example, as part of a file-name in which to store the state for a particular instantiation. The client-ID should be saved as part of the command used to restart this client (the RestartCommand) so that the client will retain the same ID after it is restarted. Certain small pieces of state might also be stored in the RestartCommand. For example, an X11 client might place a '-twoWindow' option in its RestartCommand to indicate that it should start up in two window mode when it is restarted.

The client finds the network address of the SM in a system-dependent way. On POSIX systems an environment variable called SESSION_MANAGER will contain a list of network IDs. Each id will contain the transport name followed by a slash and the (transport-specific) address. A TCP/IP address would look like this:

tcp/hostname:portnumber 

where the hostname is a fully qualified domain name. A Unix Domain address looks like this:

local/hostname:path

A DECnet address would look like this:

decnet/nodename::objname 

If multiple network IDs are specified, they should be separated by commas.

Rationale

• There was much discussion over whether the XSMP protocol should use X as the transport protocol or whether it should use its own independent transport. It was decided that it would use an independent protocol for several reasons. First, the Session Manager should be able to manage programs that do not maintain an X connection. Second, the X protocol is not appropriate to use as a general-purpose transport protocol. Third, a session might span multiple displays.

• The protocol is connection based, because there is no other way for the SM to determine reliably when clients terminate.

• It should be noted that this protocol introduces another single point of failure into the system. Although it is possible for clients to continue running after the SM has exited, this will probably not be the case in normal practice. Normally the program that starts the SM will consider the session to be terminated when the SM exits (either normally or abnormally).

• To get around this would require some sort of rendezvous server that would also introduce a single point of failure. In the absence of a generally available rendezvous server, XSMP is kept simple in the hopes of making simple reliable SMs.

Some clients may wish to manage the programs they start. For example, a mail program could start a text editor for editing the text of a mail message. A client that does this is a session manager itself; it should supply the clients it starts with the appropriate connection information (i.e., the SESSION_MANAGER environment variable) that specifies a connection to itself instead of to the top level session manager.

Each client has associated with it a list of properties. A property set by one client is not visible to any other client. These properties are used for the client to inform the SM of the client's current state. When a client initially connects to the SM, there are no properties set.

Data Types

XSMP messages contain several types of data. Both the SM and the client always send messages in their native byte order. Thus, both sides may need to byte-swap the messages received. The need to do byte swapping is determined at run-time by the ICE protocol. If an invalid value is specified for a field of any of the enumerated types, a BadValue error message must be sent by the receiver of the message to the sender of the message.

Protocol Setup and Message Format

To start the XSMP protocol, the client sends the server an ICE ProtocolSetup message. All XSMP mes-sages are in the standard ICE message format. The message's major opcode is assigned to XSMP by ICE at run-time. The different parties (client and SM) may be assigned different major opcodes for XSMP.

Once assigned, all XSMP messages issued by this party will use the same major opcode. The message'sminor opcode specifies which protocol message this message contains. 6. Client Identification String A client ID is a string of XPCS characters encoded in ISO Latin 1 (ISO 8859-1). No null characters areallowed in this string. The client ID string is used in the RegisterClient and RegisterClientReply messages. Client IDs consist of the pieces described below. T he ID is formed by concatenating the pieces insequence, without separator characters. All pieces are padded on the left with '0' characters so as to fill the specified length. Decimal numbers are encoded using the characters 0' through 9', and hexadecimal num-bers using the characters 0' through 9' and A' t hrough F'.

• Version. This is currently the character `1'.
• Address type and address. The address type will be one of

• '1' a 4-byte IPv4 address encoded as 8 hexadecimal digits

• '2' a 6-byte DECNET address encoded as 12 hexadecimal digits

• '6' a 16-byte IPv6 address encoded as 32 hexadecimal digits

• The address is the one of the network addresses of the machine where the session manager (not theclient) is running. For example, the IP address 198.112.45.11 would be encoded as the string 'C6702D0B'.

• Time stamp. A 13-digit decimal number specifying the number of milliseconds since 00:00:00 UTC,January 1, 1970.
• Process-ID type and process-ID. The process-ID type will be one of

• '1' a POSIX process-ID encoded as a 10-digit decimal number.

• The process-ID is the process-ID of the session manager, not of a client.

• Sequence number. This is a four-digit decimal number. It is incremented every time the session man-ager creates an ID. After reaching 9999 it wraps to 0000.

Rationale

• Once a client ID has been assigned to the client, the client keeps this ID indefinitely. If the client is terminated and restarted, it will be reassigned the same ID. It is desirable to be able to pass client IDs around from machine to machine, from user to user, and fromsession manager to session manager, while retaining the identity of the client. This, combined with the indefinite persistence of client IDs, means that client IDs need to be glob-ally unique. The construction specified above will ensure that any client ID created by any user, session manager, and machine will be different from any other.

Protocol

The protocol consists of a sequence of messages as described below. Each message type is specified by an ICE minor opcode. A given message type is sent either from a client to the session manager or from the session manager to a client; the appropriate direction is listed with each message's description. For each message type, the set of valid responses and possible error messages are listed. The ICE severity is given in parentheses following each error class.

RegisterClient

• Client -> SM

previous-ID

ARRAY8

Valid Responses

RegisterClientReply

Possible Errors

BadValue (CanContinue) Message Format

The client must send this message to the SM to register the client's existence. If a client is being restarted from a previous session, the previous-ID field must contain the client ID from the previous session. For new clients, previous-ID should be of zero length. If previous-ID is not valid, the SM will send a BadValue error message to the client. At this point the SM reverts to the register state and waits for another RegisterClient. The client should then send a RegisterClient with a null previous-ID field.

RegisterClientReply

• Client <- SM

client-ID

ARRAY8 Message Format

The client-ID specifies a unique identification for this client. If the client had specified an ID in the previous-ID field of the RegisterClient message, client-ID will be identical to the previously specified ID. If previous-ID was null, client-ID will be a unique ID freshly generated by the SM. The client-ID format is specified in section 6.

If the client didn't supply a previous-ID field to the RegisterClient message, the SM must send a SaveYourself message with type = Local, shutdown = False, interact-style = None, and fast = False immediately after the RegisterClientReply. The client should respond to this like any other SaveYourself message.

SaveYourself

• Client <- SM

type

SAVE_TYPE

shutdown

BOOL

interact-style

INTERACT_STYLE

fast

BOOL

Valid Responses

SetProperties, DeleteProperties, GetProperties, SaveYourselfDone, SaveYourselfPhase2Request, InteractRequest Message Format

The SM sends this message to a client to ask it to save its state. The client writes a state file and, if necessary, uses SetProperties to inform the SM of how to restart it and how to discard the saved state. During this process it can, if allowed by interact-style, request permission to interact with the user by sending an InteractRequest message. After the state has been saved, or if it cannot be successfully saved, and the properties are appropriately set, the client sends a SaveYourselfDone message. If the client wants to save additional information after all the other clients have finished changing their own state, the client should send SaveYourselfPhase2Request instead of SaveYourselfDone. The client must then freezeinteraction with the user and wait until it receives a SaveComplete, Die, or a ShutdownCancelled message.

If interact-style is None, the client must not interact with the user while saving state. If the interact-style is Errors, the client may interact with the user only if an error condition arises. If interact-style is Any, then the client may interact with the user for any purpose. This is done by sending an InteractRequest mes-sage. The SM will send an Interact message to each client that sent an InteractRequest. The client must postpone all interaction until it gets the Interact message. When the client is done interacting it should send the SM an InteractDone message. The InteractRequest message can be sent any time after a SaveYourself and before a SaveYourselfDone.

Unusual circumstances may dictate multiple interactions. The client may initiate as many InteractRequest - Interact - InteractDone sequences as it needs before it sends SaveYourselfDone.

When a client receives SaveYourself and has not yet responded SaveYourselfDone to a previous SaveYourself, it must send a SaveYourselfDone and may then begin responding as appropriate to the newly received SaveYourself.

The type field specifies the type of information that should be saved: Global, Local, or Both. The Localtype indicates that the application must update the properties to reflect its current state, send a SaveYourselfDone and continue. Specifically it should save enough information to restore the state as seen by the user of this client. It should not affect the state as seen by other users. The Global type indicates that the user wants the client to commit all of its data to permanent, globally-accessible storage. Both indicates that the client should do both of these. If Both is specified, the client should first commit the data to permanent storage before updating its SM properties.

Examples

• If a word processor was sent a SaveYourself with a type of Local, it could create a temporary file that included the current contents of the file, the location of the cursor, and other aspects of the current editing session. It would then update its RestartCommand property with enough information to find the temporary file, and its DiscardCommand with enough information to remove it.

  If a word processor was sent a SaveYourself with a type of Global, it would simply save thecurrently edited file.

  If a word processor was sent a SaveYourself with a type of Both, it would first save the currently edited file. It would then create a temporary file with information such as the current position of the cursor and what file is being edited. It would then update its Restart-Command property with enough information to find the temporary file, and its DiscardCommand with enough information to remove it.

  Once the SM has send SaveYourself to a client, it can't send another SaveYourself to that client until the client either responds with a SaveYourselfDone or the SM sends a ShutdownCancelled.

Advice to Implementors

• If the client stores local any state in a file or similar external storage, it must create a distinctcopy in response to each SaveYourself message. It must not simply refer to a previous copy, because the SM may discard that previous saved state using a DiscardCommand withoutknowing that it is needed for the new checkpoint.

The shutdown field specifies whether the system is being shut down.

Rationale

start:

• ICE protocol setup complete -> register

register:

• send RegisterClient -> collect-id

collect-id:

• receive RegisterClientReply -> idle

shutdown-cancelled:

• send SaveYourselfDone -> idle

idle: [Undoes any freeze of interaction with user.]

• receive Die -> die receive SaveYourself -> freeze-interaction send GetProperties -> idle receive GetPropertiesReply -> idle send SetProperties -> idle send DeleteProperties -> idle send ConnectionClosed -> connection-closed send SaveYourselfRequest -> idle

die:

• send ConnectionClosed -> connection-closed

freeze-interaction:

• freeze interaction with user -> save-yourself

save-yourself:

• receive ShutdownCancelled -> shutdown-cancelled send SetProperties -> save-yourself send DeleteProperties -> save-yourself send GetProperties -> save-yourself receive GetPropertiesReply -> save-yourself send InteractRequest -> interact-request send SaveYourselfPhase2Request -> waiting-for-phase2 if shutdown mode:

  • send SaveYourselfDone -> save-yourself-done

  otherwise:

  • send SaveYourselfDone -> idle

waiting-for-phase2:

• receive ShutdownCancelled -> shutdown-cancelled receive SaveYourselfPhase2 -> phase2

phase2:

• receive ShutdownCancelled -> shutdown-cancelled

• send SetProperties -> save-yourself

• send DeleteProperties -> save-yourself

• send GetProperties -> save-yourself

• receive GetPropertiesReply -> save-yourself

• send InteractRequest -> interact-request (errors only)

• if shutdown mode:

• send SaveYourselfDone -> save-yourself-done

• otherwise:

• send SaveYourselfDone -> idle

interact-request:

• receive Interact -> interact receive ShutdownCancelled -> shutdown-cancelled

interact:

• send InteractDone -> save-yourself receive ShutdownCancelled -> shutdown-cancelled

save-yourself-done: (changing state is forbidden)

• receive SaveComplete -> idle receive Die -> die receive ShutdownCancelled -> idle

connection-closed:

• client stops participating in session

Session Manager State Diagram

start:

• receive ProtocolSetup -> protocol-setup

protocol-setup:

• send ProtocolSetupReply -> register

register:

• receive RegisterClient -> acknowledge-register

acknowledge-register:

• send RegisterClientReply -> idle

idle:

• receive SetProperties -> idle receive DeleteProperties -> idle receive ConnectionClosed -> start receive GetProperties -> get-properties receive SaveYourselfRequest -> save-yourself send SaveYourself -> saving-yourself

save-yourself:

• send SaveYourself -> saving-yourself

get-properties:

• send GetPropertiesReply -> idle

saving-get-properties:

• send GetPropertiesReply -> saving-yourself

saving-yourself:

• receive InteractRequest -> saving-yourself send Interact -> saving-yourself send ShutdownCancelled -> idle receive InteractDone -> saving-yourself receive SetProperties -> saving-yourself receive DeleteProperties -> saving-yourself receive GetProperties -> saving-get-properties receive SaveYourselfPhase2Request -> start-phase2 receive SaveYourselfDone -> save-yourself-done

start-phase2:

• If all clients have sent either SaveYourselfPhase2Request or SaveYourselfDone:

  • send SaveYourselfPhase2 -> phase2

  else -> saving-yourself

phase2:

• receive InteractRequest -> saving-yourself send Interact -> saving-yourself send ShutdownCancelled -> idle receive InteractDone -> saving-yourself receive SetProperties -> saving-yourself receive DeleteProperties -> saving-yourself receive GetProperties -> saving-get-properties receive SaveYourselfDone -> save-yourself-done

save-yourself-done:

• If all clients are saved:
  • If shutting down:

    • send Die -> die

    otherwise:

    • send SaveComplete -> idle

  If some clients are not saved:

  • -> saving-yourself

die:

• SM stops accepting connections

Protocol Encoding

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associateddocumentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, m odify, merge, publish, distribute, sublicense, and/or sell copies of the Soft-ware, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portionsof the Software. THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE XCONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNEC-TION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.