The mmap modules are used for fast memory transfers
between client and server when both reside on the same host.
The client creates its mmap areas before the connection is established,
so it cannot know yet whether the server will be able to use them.
On MS Windows, where the areas are charged to the system commit limit as soon
as they are created and the server is very rarely local, the default value of
the mmap option (auto) therefore means no: it must be enabled explicitly
with mmap=yes.
The prefix for all packets and capabilities is mmap.
| Component | Link |
|---|---|
| client | xpra.client.subsystem.mmap |
| client connection | xpra.server.source.mmap |
| server | xpra.server.subsystem.mmap |
The client and server should expose the following capabilities in their hello packet
using the clipboard prefix.
The client creates an mmap backing file for each direction it wants to use:
read for receiving data from the serverwrite for sending data to the serverFor each capability, the client writes a random token at a random position within this mmap area and sends the following attributes:
| Capability | Value |
|---|---|
file |
path to the mmap backing file |
size |
size of the mmap area |
token |
random token value generated |
token_index |
position where the token was written |
token_bytes |
length of the token in bytes |
The server should attempt to open the mmap file specified, and verify that the token is found.
The client does not get to choose which directory the server opens the file from:
the server only uses the basename of the file attribute, and looks for it
in one of the directories it accepts.
Unless directories have been specified with the mmap option, these are
the server’s own mmap directory and, when the peer can be identified as
another local user, that user’s mmap directory.
Clients specifying a file anywhere else are refused and mmap is then disabled.
The file is opened relative to that directory and symbolic links are never
followed, then the file descriptor itself is verified rather than the path:
it must be a regular file, with a single link, belonging either to the server
or to the client’s user. The directory must not be writable by everyone
unless the sticky bit prevents other users from replacing files in it.
None of these checks apply to a path specified with the mmap option:
that one is chosen by the administrator and can legitimately be a symbolic
link, a device file, or a file belonging to another user.
To use this mmap file, it must write a new token
and return this information to the client.
(using the same format, excluding the file and size that the client has already specified)
The client then verifies that the mmap file can be used.
There are no specific mmap packets used, mmap is used as an encoding.
Xpra can use mmap with virtio-shmem to speed up connections between a host and guest or even between two guests.
Example steps for host to guest setup:
shmem device to your VM, ie:
DEV_NAME="shmem-xpra"
virt-install --shmem name="${DEV_NAME}",model.type=ivshmem-plain,size.unit=M,size=512"`)
echo 1 > $(find /sys/devices/ -type f -name "resource2_wc" -exec dirname "{}" \;)/enable
and start an xpra server with mmap pointing to it:
VSOCK_PORT=10000
MMAP_PATH=$(find /sys/devices/ -type f -name "resource2_wc")
xpra seamless --bind-vsock=auto:${VSOCK_PORT} --mmap=$MMAP_PATH
mmap with the same device:
DEV_NAME="shmem-xpra"
VSOCK_PORT=10000
VM_CID=$(virsh dumpxml "${DEV_NAME}" | grep cid | sed 's/[^0-9]*//g')
xpra attach vsock://"${VM_CID}":${VSOCK_PORT}/ -d mmap --mmap="/dev/shm/${DEV_NAME}"
Documentation: