This page applies to the development version of xrdp.

The following changes have been made since v0.10.x of SCP:-

• The old start session call is split into two calls:-
  • Start session no longer closes the sesman connection
  • A new connect session command is used to connect to an existing session.
• The logout and close connection commands need updating to behave correctly if called after 'start session'
• sesexec now has a connection to the xrdp process which can be used to detect disconnections, and (in the future) to request disconnections or implement reconnect functionality (#1443).

The rationale of these changes is as follows:-

• The security of the sockdir can be improved in that it no longer needs to be accessible to the xrdp process. There is an exception to this, which is if xrdp needs to connect to a chansrv process which has not been started by sesman.
• At the moment the reconnect script is called, whether or not the client has any intention of reconnecting to the session.
• Further changes are now possible to allow #2765 to be implemented.

This page contains sequence diagrams for xrdp component interactions caused by SCP calls. SCP calls are made by the following components:-

An SCP connection is initiated by a process making a connection to the sesman listening socket configured in sesman.ini. The sesman listening socket is a Unix domain socket, available to the current machine only.

All calls made to SCP must start with an authentication exchange. This allows sesman to determine the privileges to be afforded to the connecting process. At present the following authentication methods are supported:-

• Authentication via Unix Domain Socket (UDS login). The owner of the peer socket connecting to sesman is considered to be the user requesting access.
• Authentication via username and password (sys login). A username and a password are provided to sesman.

sequenceDiagram
actor C as client
participant SM as sesman

C-)+SM : Login using UDS credentials
SM-)-C : Login result
opt Login failed
destroy C
SM-XC : Closes client connection
end

sequenceDiagram
actor C as client
participant SM as sesman

C-)+SM : Login using username/password
create participant SE as sesexec
SM->SE : fork and set up a communications link
SM-)+SE: Login using this client file descriptor
SM-)SM : Sesman closes client file descriptor copy.
deactivate SM
note over C,SE: sesexec and client can exchange further messages. This might be<br/>to implement a PAM dialogue, or to handle login retries up to `MaxLoginRetry`
SE-)-SM : Login result (contains client file descriptor)
activate SM
SE-)SE : sesexec closes client file descriptor copy
SM-)-C: Login result
opt Login failed
destroy C
SM-XC : sesman closes client connection
destroy SE
SM-XSE : sesman closes sesexec connection
end

Following authentication, the client can send one or more commands to sesman, to be executed on behalf of the authorized user.

sequenceDiagram
actor C as client
participant SM as sesman
participant SE as sesexec
C-)+SM : Logout

Alt if a sesexec process without a session exists for this login
SM-)SE : Send logout request
destroy SE
SM-)SE : sesman closes sesexec connection
end

No response is sent to the client for a logout request. After logging out, a different login request may be made, perhaps for a different user.

sequenceDiagram
actor C as client
participant SM as sesman
participant SE as sesexec

C-)+SM : Close connection
destroy client

Alt if a sesexec process without a session exists for this login
destroy SE
SM-)SE : sesman closes sesexec connection
end
destroy C
SM-XC : sesman closes client connection

This is a command used when chansrv is running outside of sesman. This is most commonly encountered when chansrv is being run in a console session which is also running x11vnc.

sequenceDiagram
actor C as client
participant SM as sesman

C-)+SM : Create sockdir for the authenticated user
SM-)-C : Sockdir creation response

sequenceDiagram
actor C as client
participant SM as sesman

C-)+SM : List sessions
loop for each session the user is authorized to see
SM-)C : Session data item
end
SM-)-C : list session end

If an existing session exists for the user, the following sequence occurs:-

sequenceDiagram

actor C as client
participant SM as sesman

C-)+SM: Create session
SM-)-C: Session GUID

If no existing session exists for the user, the following sequence occurs:-

sequenceDiagram

actor C as client
participant SM as sesman

C-)+SM: Create session
alt if a sesexec process does not already exist for the connection
create participant SE as sesexec
SM->SE : fork and set up a communications link
end
SM-)SE: Create session.
deactivate SM
activate SE
SE-)SM: Create session result
deactivate SE
activate SM
SM-)-C: Create session result (including GUID if successful)
alt If session was created successfully
SM-)SM : sesman creates minimal session record.
SE-)SM : Session announce event
SM-)SM : sesman fills in complete session record.
end

The session record is completed in two stages:-

1. When sesexec passes back a successful session creation status, a minimal record is created containing the GUID. This allows the session to be located for a 'connect session' command.
2. The 'session announce event' which follows immediately allows sesman to fill in the complete session record.

The reason for this is that the 'session announce event' is also used for session recovery when sesman is restarted. We only have one place to change if extra data needs to be held by sesman about the session. The minimal session record avoids a race between the session announce event (from sesexec) and a connect session command (from the client).

This follows a create session call, and is used to get file descriptors for the display server and chansrv.

This call is only expected to be used by the xrdp process.

Following this call, the SCP connection becomes an CCP connection (Connection Control Protocol).

sequenceDiagram
participant C as xrdp
participant SM as sesman
participant SE as sesexec
participant OC as old-xrdp

C-)+SM: Connect session (GUID)
alt If session does not exist, or user does not match user for session
SM-)C : Return error status
SM-)SM: Close client file descriptor
else
SM-)SE: connect session, client file descriptor is passed
activate SE
SM-)SM: Close client file descriptor
deactivate SM
Alt if an xrdp process is already running on this session
destroy OC
SE-XOC: (CCP) ask the existing xrdp process to terminate
SE-)SE: Wait 500ms.
end
SE-)SE: Connect to display server port, getting file descriptor
SE-)SE: Connect to chansrv port, getting file descriptor
SE-)SM: Client connect event
SM-)SM: Session manager updates session database (see below)
SE-)C: Session file descriptors
Alt if this is a reconnection
SE-)SE: Run reconnect script for existing session
end
SE-)SE : Change SCP connection to a CCP connection
C-)C : Change SCP connection to a CCP connection
end

The xrdp process has a client of its own (the RDP client) which has an IP address and name. These two data items need to end up in the sesman database, where they can be extracted by a query using xrdp-sesadmin.

xrdp is responsible for obtaining and vetting these data items. They are passed to sesman as part of the connect session message. They are then passed to sesexec, and finally back to sesman as the 'connect event' shown in the diagram above.