allow authenticated command line clients to control the server

[Antoine Martin]

we should be able to control:

• sound (stop, start)
• change current encoding
• compression (switch to lz4 or zlib)
• debugging
• suspend/resume window updates

etc

[Antoine Martin]

• r4776 added support for controlling the server via "xpra control .." (implemented compression toggle)
• r4782 adds support for sound (stop/start) and window updates (suspend/resume)
• r4783 fixes the man page
• r4784 small fix + r4785 improves error reporting
• r4802 minor fixes, add "name" command

Good enough for a round of testing.
This will be very useful for implementing more selective debugging (#411).

Notes:

• older clients may not support sound stop/start gracefully...
• the examples below use local servers (":10") because it is easier, but any authenticated client can control the server
• we try our best to validate input and report errors back to the client, but the full details will generally be in the server log

Undocumented features...:

• since the exact internal commands are likely to evolve, the only reliable documentation for the "control" subcommands is the code itself (see changesets for location)
• arguments are passed to the functions we delegate to, and some of those functions support optional arguments. For example: "control sound-output start [codec]" : at present, the codec is usually chosen automatically, but may be specified as an extra argument - though again, this may change.. beware, this is not an API.

---

Testing

Unless otherwise stated, all the commands given below should exit with no error code ("0"):

xpra ...
echo $?
0

• "help" should give the list of supported commands:

  $ xpra control :10 help
  control supports: hello, compression, sound-output, suspend, resume, name
  

• lz4 / zlib switch:
  • start server
  • connect client
  • verify compression used:

    $ xpra info | grep connection.compression=
    client.connection.compression=lz4
    

  • switch to the other one:

    xpra control :10 compression zlib
    

  • verify the new compression is used:

    $ xpra info | grep connection.compression=
    client.connection.compression=zlib
    

• suspend/resume window updates:
  • start application with regular screen updates
  • stop client refresh:

    xpra control :10 suspend
    

  • verify that all window updates have stopped (note: clicks and keypresses will not be seen but are still processed by the applications - we may want to change that), that the client doesn't misbehave, etc
  • verify using xpra info:

    $ xpra info | grep client.suspended=
    client.suspended=True
    

  • resume window updates:

    xpra control :10 resume
    

  • verify things are back to normal immediately
  • verify using xpra info:

    $ xpra info | grep client.suspended=
    client.suspended=False
    

• stop/start sound:
  • start application with sound
  • stop sound:

    xpra control :10 sound-output stop
    

  • verify sound has stopped and that client doesn't misbehave or cause the sound to restart (use XPRA_SOUND_DEBUG=1 to get more debug logging)
  • verify that the tray menu shows the sound as "off"
  • verify the server sound state:

    $ xpra info | grep speaker.state
    client.speaker.state=inactive
    

  • start sound again (also try via the tray menu):

    xpra control :10 sound-output start
    

  • verify that the sound is playing normally again (without stutter or repeated overruns/underruns)
  • verify the server sound state:

    $ xpra info | grep speaker.state
    client.speaker.state=active
    

• invalid commands should return an error and set a non-zero exitcode:

  $ xpra control :10 invalid
  server returned error code 6
  invalid command
  $ echo $?
  13
  

• invalid arguments should return an error and set a non-zero exitcode:

  $ xpra control :10 compression 123
  server returned error code 5
  invalid argument 1: must be one of: lz4, zlib
  $ echo $?
  13
  

• commands with invalid number of arguments should fail:

  $ xpra control :10 compression 123 456
  server returned error code 4
  invalid number of arguments: 2 expected
  $ echo $?
  13
  

• older servers do not understand the "control" request, and the newer client should say so and set and errorcode:

  $ xpra control :10 hello
  server does not support control command
  $ echo $?
  12
  

• older clients do not support the "control" mode and should set and errorcode:

  $ xpra control :10 hello
  (...)
  xpra: error: invalid mode 'control'
  $ echo $?
  2
  

[Antoine Martin]

r4855 adds "fadein" and "fadeout" sound control commands.
ie:

xpra control :10 sound-output fadeout

r4860 adds support for an optional fadeout delay, the command becomes:

xpra control :10 sound-output fadeout 500

The delay is specified in milliseconds (in the example: 0.5 seconds)

[alas]

Connecting with an osx client via command line, and trying to enter the commands listed within the same terminal shell I get no response. The commands type, but don't seem to be received/interpreted at all.

osx client 0.11.0-r4855; fedora19 server 0.11.0-r4840

2013-12-04 18:25:33,800 GL Extension GL_KHR_debug unavailable
2013-12-04 18:27:04,446 re-starting speaker because of overrun
2013-12-04 18:27:04,912 using audio codec: MPEG 1 Audio, Layer 3 (MP3)
xpra control :16 help
xpra control :10 help
xpra control :16 compression zlib
xpra control :10 compression zlib
xpra info } grep connection.compression=
xpra info | grep connection.compression=

I assume there's something painfully obvious that I'm missing?

Maybe XPRA_CONTROL=1?

[Antoine Martin]

afarr: unless you're running an xpra server on osx display :10 or :16, xpra is simply failing to connect since you're not specifying a valid connection point.
This should be obvious by removing the '| hero' from the command line.

[alas]

I was running the xpra session on display :16 of the linux server, then connecting to it by means of the osx terminal ./xpra attach tcp:stuff:1202

Should I be specifying the port on the client side, rather than the server-side specified display? (I'll keep poking at it and see what I see in the meantime.)

[Antoine Martin]

Please post the exact commands that you've used, the ones from comment:4 are confusing and look wrong.

Please also try another client OS (Fedora?), maybe OSX has problems.

[alas]

I launched the xpra server on a just-yum-updated Fedora 19 vm with the command dbus-launch xpra --no-daemon --bind-tcp=0.0.0.0:1202 --start-child=xterm --start-child=xterm start :16

I then launched the osx client through a terminal window with the command ./xpra attach tcp:10.0.32.172:1202 --opengl=on in the instance mentioned in comment:4.

The client outputted its usual startup output... the last 3 lines of which I copied, hoping it would make it apparent exactly where I was trying to use the commands from.

In the terminal window, once I'd gotten that usual output, I tried to enter the commands that I copied & pasted in comment:4. I used xpra control :16 help to start because I'd specified display :16 on the server side (and hoped that it would thusly be interpreted by the session).

As you can see though, I got no response from the server.

We ran into some wrinkles with the windows client, but I'll try that and maybe a fedora soon.

[Antoine Martin]

If you're typing those "xpra control" commands from within an xpra session (therefore running on the server already), then changing client OS and version will make no difference at all.
BTW, saying "within the same terminal shell" is confusing: the OSX command line is a shell too.

I don't see how it is possible for "xpra control" not to print anything on screen, at least an error of some sort.
It seems you may also have run "xpra info", and that always returns something. So something seems to be very wrong with your setup. Does the server even receive a new connection when you run those commands, or are those commands not doing anything at all?

---

Anyway, r4865 adds the ability to change window scaling on the fly too (which will also need testing), like so:

xpra control DISPLAY scaling WINDOW-ID scaling-value

Where WINDOW-ID can be found via "xpra info", or "*" can be used as wildcard.
The scaling-value takes the same form as the hardcoded ones already documented here: wiki/CSC.

Here are some examples:

• scale window "1" by half:

  xpra control :10 scaling 1 1:2
  

• scale all windows by two thirds:

  xpra control :10 scaling "*" 2:3
  

[alas]

Testing with osx client 0.11.0-r4905 and fedora 19 server 0.11.0-r4904.

It looks like the suspend command xpra control :16 suspend stops the video playback, but the sound continues. The resume command xpra control :16 resume not only resumes the video, but brings it back in sync with the sound which had continued all along.

Compression changes, with your 0.11.0-r4903 osx client build, seem to work, but are not displayed by the Xpra session-info window, though xpra info :16 | grep 'compression' shows the compression to have changed.

The name function seems to work (though I was only able to determine that with recourse to an xpra info call).

The sound-output stop, start, fadeout, and fadein all seem to work beautifully.

It would be nice to see more verbosity in the xpra control :display help command... when it is a little more settled.

[Antoine Martin]

suspend stops the video playback, but the sound continues

That's the idea, we have control commands for both. Mostly just a PoC at this point. Not sure how useful that is going to be.

Compression changes .. but are not displayed by the Xpra session-info window

That's because the client compression is not changed, only the server one.
Remember that network packets flow in both directions, this affects sending only. (and although we could add protocol support for telling the client to follow suit - I don't think it is worth the complexity, as the client sends very little data compared to the server, so compression really doesn't matter much in this direction)

Note: where lz4 makes the most difference is when we send fairly large amounts of data and not already compressed with a picture encoding. That is:

• cursors (usually around 4 to 10KB)
• clipboard data (varies - has an upper limit)
• picture data in RGB encoding (or when we send smaller regions as RGB with h264/vpx video encoders)
• hello packets (non-critical as this happens just once on startup)

It would be nice to see more verbosity in the xpra control :display help command

Yes, it would be...

[Antoine Martin]

Further enhancements:

• r5145 allows us to request the client to show the "session info" dialog
• r5146 allows us to choose which tab is shown (both from keyboard shortcuts and remote server requests)

Use it like so:

xpra control :10 client show_session_info

or:

xpra control :10 client show_session_info Statistics

[Antoine Martin]

r5148 re-uses the same mechanism so we can now forward bencode/rencode and zlib/lz4 changes to the client:

xpra control :10 encoder bencode

Causes this on the client:

switching to bencode on server request

Which can be verified with:

xpra info | egrep "connection.encoder=|connection.compression="

Showing:

client.connection.compression=lz4
client.connection.encoder=bencode

---

This was handy for testing and finding an existing bug: this causes the connection to drop instantly:

xpra control :10 client show_session_info Statistics
xpra control :10 encoder bencode

with improved error handling and logging from r5149 + r5150, we see:

None value in 'hello' packet->[1]->value for key='window[1].property.scaling'
error in write format loop
Traceback (most recent call last):
  File "/usr/lib64/python2.7/site-packages/xpra/net/protocol.py", line 394, in _write_format_thread_loop
    self._add_packet_to_queue(*self._get_packet_cb())
  File "/usr/lib64/python2.7/site-packages/xpra/net/protocol.py", line 405, in _add_packet_to_queue
    chunks, proto_flags = self.encode(packet)
  File "/usr/lib64/python2.7/site-packages/xpra/net/protocol.py", line 576, in encode
    raise e
ValueError: cannot encode '[2, {'network.bencode': True, 'keyboard.keysym.Hangul': 130, 'window[...

We have an illegal None value in the window's scaling property, this is fixed in r5151 (should be backported too).

There are enough changes here to warrant more testing, especially with the bencoder enabled at both ends as this is the only encoder supported by html5 (#473) and java clients. Re-opening the bug.

[Smo]

Tested these new functions

xpra control :13 client show_session_info
client control command 'show_session_info' forwarded
$ xpra control :13 client show_session_info Statistics
client control command 'show_session_info' forwarded
$ xpra control :13 client show_session_info Statistics
client control command 'show_session_info' forwarded
$ xpra control :13 encoder bencode
success
$ xpra info | egrep "connection.encoder=|connection.compression="
client.connection.compression=lz4
client.connection.encoder=bencode

All worked with no issue

[Antoine Martin]

Note: some improvements in this area for 0.12:

• r5316: proxy server supports "stop DISPLAY" command to stop a specific proxy instance
• r5321: "quality", "min-quality", "speed" and "min-speed" for all/individual windows (see commit message for details)

[Antoine Martin]

Important change in 0.14 (see r6664): the order of the arguments has changed so that all the commands use a similar structure, with the windows IDs at the end (if any).
Here are some examples:

• Set auto-refresh to 0.5 seconds for all windows (the two versions are equivalent):

  xpra control auto-refresh 0.5
  xpra control auto-refresh 0.5 '*'
  

• Disable (value=0) auto-refresh for window id 4:

  xpra control auto-refresh 0 4
  

• Full quality refresh of window 2 and 7:

  xpra control refresh 2 7
  

• Set scaling to 1:3 for all windows:

  xpra control scaling 1:3
  

• Disable scaling for window 5 and 6:

  xpra control scaling 1:1 5 6
  

• Set minimum quality to 60 for all windows:

  xpra control min-quality 60 '*'
  

• In 0.14, we also add an optional strict (or nostrict) argument to the encoding control:

  xpra control encoding strict jpeg
  

• Use nostrict to return to the default, more dynamic encoding selection. Here we switch windows 5 and 8 to h264:

  xpra control encoding nostrict h264 5 8
  

etc...

When specifying a list of windows, you can leave it empty to imply all the windows or specify * which has the advantage of being more explicit.

[aradtech]

I am unable to get the xpra control scaling command to work for me. I am using
Server Linux Fedora 20 0.14.0 6898 2014-07-16

XPRA_SCALING=1 xpra start :100 --start-child=xterm --no-daemon --bind-tcp=0.0.0.0:10000

Windows Client
Version 0.14.0 6896 2014-07-14

xpra attach tcp:clientip:10000

get a xterm start up firefox in it

then on the server I issue the following commands

[aradtech@localhost .xpra]$ xpra control :100 scaling 1:1 "*"
scaling set to None on window [1, 2, 14] for 1 clients
[aradtech@localhost .xpra]$ xpra control :100 scaling 2:3 "*"
scaling set to None on window [1, 2, 14] for 1 clients
[aradtech@localhost .xpra]$ xpra control :100 scaling 2:3 "*"
scaling set to None on window [1, 2, 14] for 1 clients
[aradtech@localhost .xpra]$ xpra control :100 scaling 1:3 "*"

as you can see it always says that scaling is set to none , no matter what scaling factor is set to.

I was also unable to figure out how to send that command from the client side to server side so perhaps some clarification on how to go from remote to server using tcp with the control command.

Also I am using x264 encoding.

[Antoine Martin]

Note:

• XPRA_SCALING=1 is not necessary, scaling is enabled by default.
• for debugging, you can use -d scaling

This has been broken for a very long time! (we need regression tests)
r6899 fixes this (and will need to be backported).

As for sending from client to server, there are examples you can use:

• xpra control itself
• tests/xpra/clients/test_change_settings.py does exactly that (the logic for connecting and authenticating is in the superclass it shares with xpra control)

[Antoine Martin]

Can I close this?

[Antoine Martin]

Improvement to logging control in r8377: we only enable / disable logging on the loggers that match ALL the categories supplied. This makes it much more useful as it is now much more selective if needed.
ie:

xpra control :10 debug enable x11 focus

Will not enable focus debugging on loggers that are not both x11' and focus.

[migration script]

this ticket has been moved to: ​https://github.com/Xpra-org/xpra/issues/461