Saved searches
Use saved searches to filter your results more quickly
Cancel Create saved search
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
xtermjs / xterm.js Public
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support reverse-wraparound mode? #2716
backspace opened this issue Feb 12, 2020 · 12 comments · Fixed by #2724
Support reverse-wraparound mode? #2716
backspace opened this issue Feb 12, 2020 · 12 comments · Fixed by #2724
type/enhancement Features or improvements to existing features
Comments
backspace commented Feb 12, 2020 •
I’m implementing a highly-restricted terminal with Xterm.js to allow users to edit their desired remote execution command before they connect to a true terminal. The editable portion of the line is only at the end; the rest represents the full command that one would use to perform the same action in a non-web terminal.
It’s a bit hackish to be interpreting keyboard events to edit a string, but it’s been working well enough. However, I’ve now found that if the editable part of the command wraps to another line, backspacing doesn’t wrap to the previous line. I found this Super User answer that suggests I could use “reverse-wraparound mode” in a true xterm, but sending that to the Xterm.js terminal didn’t change the behaviour.
Reverse-wraparound mode is mentioned in some comments in Xterm.js’s input handler, but it seems like it’s not handled.
Is there any chance that this mode will be supported? If not I can surely detect whether backspacing has reached the beginning of the line and move to the previous one if necessary, but I thought I’d ask in case there’s hope that this will be added or if there’s something I’m missing, because handling it manually seems like it’ll add more brittleness. If there’s any desire for it to be incorporated into Xterm.js, I could try making a PR!
Thanks for all the work on this, it works perfectly once the remote session has begun, it’s impressively powerful ��
The text was updated successfully, but these errors were encountered:
Running containers
Docker runs processes in isolated containers. A container is a process which runs on a host. The host may be local or remote. When an you execute docker run , the container process that runs is isolated in that it has its own file system, its own networking, and its own isolated process tree separate from the host.
This page details how to use the docker run command to run containers.
General form
A docker run command takes the following form:
The docker run command must specify an image reference to create the container from.
Image references
The image reference is the name and version of the image. You can use the image reference to create or run a container based on an image.
- docker run IMAGE[:TAG][@DIGEST]
- docker create IMAGE[:TAG][@DIGEST]
An image tag is the image version, which defaults to latest when omitted. Use the tag to run a container from specific version of an image. For example, to run version 23.10 of the ubuntu image: docker run ubuntu:23.10 .
Image digests
Images using the v2 or later image format have a content-addressable identifier called a digest. As long as the input used to generate the image is unchanged, the digest value is predictable.
The following example runs a container from the alpine image with the sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 digest:
Options
[OPTIONS] let you configure options for the container. For example, you can give the container a name ( —name ), or run it as a background process ( -d ). You can also set options to control things like resource constraints and networking.
Commands and arguments
You can use the [COMMAND] and [ARG. ] positional arguments to specify commands and arguments for the container to run when it starts up. For example, you can specify sh as the [COMMAND] , combined with the -i and -t flags, to start an interactive shell in the container (if the image you select has an sh executable on PATH ).
Note
Depending on your Docker system configuration, you may be required to preface the docker run command with sudo . To avoid having to use sudo with the docker command, your system administrator can create a Unix group called docker and add users to it. For more information about this configuration, refer to the Docker installation documentation for your operating system.
Foreground and background
When you start a container, the container runs in the foreground by default. If you want to run the container in the background instead, you can use the —detach (or -d ) flag. This starts the container without occupying your terminal window.
While the container runs in the background, you can interact with the container using other CLI commands. For example, docker logs lets you view the logs for the container, and docker attach brings it to the foreground.
For more information about docker run flags related to foreground and background modes, see:
- docker run —detach : run container in background
- docker run —attach : attach to stdin , stdout , and stderr
- docker run —tty : allocate a pseudo-tty
- docker run —interactive : keep stdin open even if not attached
For more information about re-attaching to a background container, see docker attach .
Container identification
You can identify a container in three ways:
| Identifier type | Example value |
|---|---|
| UUID long identifier | f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778 |
| UUID short identifier | f78375b1c487 |
| Name | evil_ptolemy |
The UUID identifier is a random ID assigned to the container by the daemon.
The daemon generates a random string name for containers automatically. You can also defined a custom name using the —name flag. Defining a name can be a handy way to add meaning to a container. If you specify a name , you can use it when referring to the container in a user-defined network. This works for both background and foreground Docker containers.
A container identifier is not the same thing as an image reference. The image reference specifies which image to use when you run a container. You can’t run docker exec nginx:alpine sh to open a shell in a container based on the nginx:alpine image, because docker exec expects a container identifier (name or ID), not an image.
While the image used by a container is not an identifier for the container, you find out the IDs of containers using an image by using the —filter flag. For example, the following docker ps command gets the IDs of all running containers based on the nginx:alpine image:
For more information about using filters, see Filtering
Container networking
Containers have networking enabled by default, and they can make outgoing connections. If you’re running multiple containers that need to communicate with each other, you can create a custom network and attach the containers to the network.
When multiple containers are attached to the same custom network, they can communicate with each other using the container names as a DNS hostname. The following example creates a custom network named my-net , and runs two containers that attach to the network.
For more information about container networking, see Networking overview
Filesystem mounts
By default, the data in a container is stored in an ephemeral, writable container layer. Removing the container also removes its data. If you want to use persistent data with containers, you can use filesystem mounts to store the data persistently on the host system. Filesystem mounts can also let you share data between containers and the host.
Docker supports two main categories of mounts:
- Volume mounts
- Bind mounts
Volume mounts are great for persistently storing data for containers, and for sharing data between containers. Bind mounts, on the other hand, are for sharing data between a container and the host.
You can add a filesystem mount to a container using the —mount flag for the docker run command.
The following sections show basic examples of how to create volumes and bind mounts. For more in-depth examples and descriptions, refer to the section of the storage section
in the documentation.
Volume mounts
To create a volume mount:
The --mount flag takes two parameters in this case: source and target . The value for the source parameter is the name of the volume. The value of target is the mount location of the volume inside the container. Once you've created the volume, any data you write to the volume is persisted, even if you stop or remove the container:
/foo/hello.txt The target must always be an absolute path, such as /src/docs . An absolute path starts with a / (forward slash). Volume names must start with an alphanumeric character, followed by a-z0-9 , _ (underscore), . (period) or — (hyphen).
Bind mounts
To create a bind mount:
In this case, the —mount flag takes three parameters. A type ( bind ), and two paths. The source path is a the location on the host that you want to bind mount into the container. The target path is the mount destination inside the container.
Bind mounts are read-write by default, meaning that you can both read and write files to and from the mounted location from the container. Changes that you make, such as adding or editing files, are reflected on the host filesystem:
/foo/hello.txt Exit status
The exit code from docker run gives information about why the container failed to run or why it exited. The following sections describe the meanings of different container exit codes values.
125
Exit code 125 indicates that the error is with Docker daemon itself.
Exit code 126 indicates that the specified contained command can't be invoked. The container command in the following example is: /etc; echo $? .
Exit code 127 indicates that the contained command can't be found.
Any exit code other than 125 , 126 , and 127 represent the exit code of the provided container command.
The operator can also adjust the performance parameters of the container:
| Option | Description |
|---|---|
| -m , —memory=»» | Memory limit (format: [] ). Number is a positive integer. Unit can be one of b , k , m , or g . Minimum is 6M. |
| —memory-swap=»» | Total memory limit (memory + swap, format: [] ). Number is a positive integer. Unit can be one of b , k , m , or g . |
| —memory-reservation=»» | Memory soft limit (format: [] ). Number is a positive integer. Unit can be one of b , k , m , or g . |
| —kernel-memory=»» | Kernel memory limit (format: [] ). Number is a positive integer. Unit can be one of b , k , m , or g . Minimum is 4M. |
| -c , —cpu-shares=0 | CPU shares (relative weight) |
| —cpus=0.000 | Number of CPUs. Number is a fractional number. 0.000 means no limit. |
| —cpu-period=0 | Limit the CPU CFS (Completely Fair Scheduler) period |
| —cpuset-cpus=»» | CPUs in which to allow execution (0-3, 0,1) |
| —cpuset-mems=»» | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. |
| —cpu-quota=0 | Limit the CPU CFS (Completely Fair Scheduler) quota |
| —cpu-rt-period=0 | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| —cpu-rt-runtime=0 | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. |
| —blkio-weight=0 | Block IO weight (relative weight) accepts a weight value between 10 and 1000. |
| —blkio-weight-device=»» | Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT ) |
| —device-read-bps=»» | Limit read rate from a device (format: :[] ). Number is a positive integer. Unit can be one of kb , mb , or gb . |
| —device-write-bps=»» | Limit write rate to a device (format: :[] ). Number is a positive integer. Unit can be one of kb , mb , or gb . |
| —device-read-iops=»» | Limit read rate (IO per second) from a device (format: : ). Number is a positive integer. |
| —device-write-iops=»» | Limit write rate (IO per second) to a device (format: : ). Number is a positive integer. |
| —oom-kill-disable=false | Whether to disable OOM Killer for the container or not. |
| —oom-score-adj=0 | Tune container’s OOM preferences (-1000 to 1000) |
| —memory-swappiness=»» | Tune a container’s memory swappiness behavior. Accepts an integer between 0 and 100. |
| —shm-size=»» | Size of /dev/shm . The format is . number must be greater than 0 . Unit is optional and can be b (bytes), k (kilobytes), m (megabytes), or g (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses 64m . |
User memory constraints
We have four ways to set user memory usage:
| Option | Result |
|---|---|
| memory=inf, memory-swap=inf (default) | There is no memory limit for the container. The container can use as much memory as needed. |
| memory=L | (specify memory and set memory-swap as -1 ) The container is not allowed to use more than L bytes of memory, but can use as much swap as is needed (if the host supports swap memory). |
| memory=L | (specify memory without memory-swap) The container is not allowed to use more than L bytes of memory, swap plus memory usage is double of that. |
| memory=L | (specify both memory and memory-swap) The container is not allowed to use more than L bytes of memory, swap plus memory usage is limited by S. |
We set nothing about memory, this means the processes in the container can use as much memory and swap memory as they need.
We set memory limit and disabled swap memory limit, this means the processes in the container can use 300M memory and as much swap memory as they need (if the host supports swap memory).
We set memory limit only, this means the processes in the container can use 300M memory and 300M swap memory, by default, the total virtual memory size (—memory-swap) will be set as double of memory, in this case, memory + swap would be 2*300M, so processes can use 300M swap memory as well.
We set both memory and swap memory, so the processes in the container can use 300M memory and 700M swap memory.
Memory reservation is a kind of memory soft limit that allows for greater sharing of memory. Under normal circumstances, containers can use as much of the memory as needed and are constrained only by the hard limits set with the -m / —memory option. When memory reservation is set, Docker detects memory contention or low memory and forces containers to restrict their consumption to a reservation limit.
Always set the memory reservation value below the hard limit, otherwise the hard limit takes precedence. A reservation of 0 is the same as setting no reservation. By default (without reservation set), memory reservation is the same as the hard memory limit.
Memory reservation is a soft-limit feature and does not guarantee the limit won’t be exceeded. Instead, the feature attempts to ensure that, when memory is heavily contended for, memory is allocated based on the reservation hints/setup.
The following example limits the memory ( -m ) to 500M and sets the memory reservation to 200M.
Under this configuration, when the container consumes memory more than 200M and less than 500M, the next system memory reclaim attempts to shrink container memory below 200M.
The following example set memory reservation to 1G without a hard memory limit.
The container can use as much memory as it needs. The memory reservation setting ensures the container doesn’t consume too much memory for long time, because every memory reclaim shrinks the container’s consumption to the reservation.
By default, kernel kills processes in a container if an out-of-memory (OOM) error occurs. To change this behaviour, use the —oom-kill-disable option. Only disable the OOM killer on containers where you have also set the -m/—memory option. If the -m flag is not set, this can result in the host running out of memory and require killing the host’s system processes to free memory.
The following example limits the memory to 100M and disables the OOM killer for this container:
The following example, illustrates a dangerous way to use the flag:
The container has unlimited memory which can cause the host to run out memory and require killing system processes to free memory. The —oom-score-adj parameter can be changed to select the priority of which containers will be killed when the system is out of memory, with negative scores making them less likely to be killed, and positive scores more likely.
Kernel memory constraints
Kernel memory is fundamentally different than user memory as kernel memory can’t be swapped out. The inability to swap makes it possible for the container to block system services by consuming too much kernel memory. Kernel memory includes：
- stack pages
- slab pages
- sockets memory pressure
- tcp memory pressure
You can setup kernel memory limit to constrain these kinds of memory. For example, every process consumes some stack pages. By limiting kernel memory, you can prevent new processes from being created when the kernel memory usage is too high.
Kernel memory is never completely independent of user memory. Instead, you limit kernel memory in the context of the user memory limit. Assume «U» is the user memory limit and «K» the kernel limit. There are three possible ways to set limits:
| Option | Result |
|---|---|
| U != 0, K = inf (default) | This is the standard memory limitation mechanism already present before using kernel memory. Kernel memory is completely ignored. |
| U != 0, K < U | Kernel memory is a subset of the user memory. This setup is useful in deployments where the total amount of memory per-cgroup is overcommitted. Overcommitting kernel memory limits is definitely not recommended, since the box can still run out of non-reclaimable memory. In this case, you can configure K so that the sum of all groups is never greater than the total memory. Then, freely set U at the expense of the system’s service quality. |
| U != 0, K > U | Since kernel memory charges are also fed to the user counter and reclamation is triggered for the container for both kinds of memory. This configuration gives the admin a unified view of memory. It is also useful for people who just want to track kernel memory usage. |
We set memory and kernel memory, so the processes in the container can use 500M memory in total, in this 500M memory, it can be 50M kernel memory tops.
We set kernel memory without -m, so the processes in the container can use as much memory as they want, but they can only use 50M kernel memory.
Swappiness constraint
By default, a container’s kernel can swap out a percentage of anonymous pages. To set this percentage for a container, specify a —memory-swappiness value between 0 and 100. A value of 0 turns off anonymous page swapping. A value of 100 sets all anonymous pages as swappable. By default, if you are not using —memory-swappiness , memory swappiness value will be inherited from the parent.
For example, you can set:
Setting the —memory-swappiness option is helpful when you want to retain the container’s working set and to avoid swapping performance penalties.
CPU share constraint
By default, all containers get the same proportion of CPU cycles. This proportion can be modified by changing the container’s CPU share weighting relative to the weighting of all other running containers.
To modify the proportion from the default of 1024, use the -c or —cpu-shares flag to set the weighting to 2 or higher. If 0 is set, the system will ignore the value and use the default of 1024.
The proportion will only apply when CPU-intensive processes are running. When tasks in one container are idle, other containers can use the left-over CPU time. The actual amount of CPU time will vary depending on the number of containers running on the system.
For example, consider three containers, one has a cpu-share of 1024 and two others have a cpu-share setting of 512. When processes in all three containers attempt to use 100% of CPU, the first container would receive 50% of the total CPU time. If you add a fourth container with a cpu-share of 1024, the first container only gets 33% of the CPU. The remaining containers receive 16.5%, 16.5% and 33% of the CPU.
On a multi-core system, the shares of CPU time are distributed over all CPU cores. Even if a container is limited to less than 100% of CPU time, it can use 100% of each individual CPU core.
For example, consider a system with more than three cores. If you start one container with -c=512 running one process, and another container with -c=1024 running two processes, this can result in the following division of CPU shares:
PID container CPU CPU share 100 0 100% of CPU0 101 1 100% of CPU1 102 2 100% of CPU2 CPU period constraint
The default CPU CFS (Completely Fair Scheduler) period is 100ms. We can use —cpu-period to set the period of CPUs to limit the container’s CPU usage. And usually —cpu-period should work with —cpu-quota .
If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms.
In addition to use —cpu-period and —cpu-quota for setting CPU period constraints, it is possible to specify —cpus with a float number to achieve the same purpose. For example, if there is 1 CPU, then —cpus=0.5 will achieve the same result as setting —cpu-period=50000 and —cpu-quota=25000 (50% CPU).
The default value for —cpus is 0.000 , which means there is no limit.
Cpuset constraint
We can set cpus in which to allow execution for containers.
This means processes in container can be executed on cpu 1 and cpu 3.
This means processes in container can be executed on cpu 0, cpu 1 and cpu 2.
We can set mems in which to allow execution for containers. Only effective on NUMA systems.
This example restricts the processes in the container to only use memory from memory nodes 1 and 3.
This example restricts the processes in the container to only use memory from memory nodes 0, 1 and 2.
CPU quota constraint
The —cpu-quota flag limits the container’s CPU usage. The default 0 value allows the container to take 100% of a CPU resource (1 CPU). The CFS (Completely Fair Scheduler) handles resource allocation for executing processes and is default Linux Scheduler used by the kernel. Set this value to 50000 to limit the container to 50% of a CPU resource. For multiple CPUs, adjust the —cpu-quota as necessary. For more information, see the CFS documentation on bandwidth limiting
Block IO bandwidth (Blkio) constraint
By default, all containers get the same proportion of block IO bandwidth (blkio). This proportion is 500. To modify this proportion, change the container’s blkio weight relative to the weighting of all other running containers using the —blkio-weight flag.
Note:
The blkio weight setting is only available for direct IO. Buffered IO is not currently supported.
The —blkio-weight flag can set the weighting to a value between 10 to 1000. For example, the commands below create two containers with different blkio weight:
If you do block IO in the two containers at the same time, by, for example:
You'll find that the proportion of time is the same as the proportion of blkio weights of the two containers.
The —blkio-weight-device=»DEVICE_NAME:WEIGHT» flag sets a specific device weight. The DEVICE_NAME:WEIGHT is a string containing a colon-separated device name and weight. For example, to set /dev/sda device weight to 200 :
If you specify both the —blkio-weight and —blkio-weight-device , Docker uses the —blkio-weight as the default weight and uses —blkio-weight-device to override this default with a new value on a specific device. The following example uses a default weight of 300 and overrides this default on /dev/sda setting that weight to 200 :
The —device-read-bps flag limits the read rate (bytes per second) from a device. For example, this command creates a container and limits the read rate to 1mb per second from /dev/sda :
The —device-write-bps flag limits the write rate (bytes per second) to a device. For example, this command creates a container and limits the write rate to 1mb per second for /dev/sda :
Both flags take limits in the :[unit] format. Both read and write rates must be a positive integer. You can specify the rate in kb (kilobytes), mb (megabytes), or gb (gigabytes).
The —device-read-iops flag limits read rate (IO per second) from a device. For example, this command creates a container and limits the read rate to 1000 IO per second from /dev/sda :
The —device-write-iops flag limits write rate (IO per second) to a device. For example, this command creates a container and limits the write rate to 1000 IO per second to /dev/sda :
Both flags take limits in the : format. Both read and write rates must be a positive integer.
Additional groups
By default, the docker container process runs with the supplementary groups looked up for the specified user. If one wants to add more to that list of groups, then one can use this flag:
Runtime privilege and Linux capabilities
| Option | Description |
|---|---|
| —cap-add | Add Linux capabilities |
| —cap-drop | Drop Linux capabilities |
| —privileged | Give extended privileges to this container |
| —device=[] | Allows you to run devices inside the container without the —privileged flag. |
By default, Docker containers are «unprivileged» and cannot, for example, run a Docker daemon inside a Docker container. This is because by default a container is not allowed to access any devices, but a «privileged» container is given access to all devices (see the documentation on cgroups devices
The —privileged flag gives all capabilities to the container. When the operator executes docker run —privileged , Docker will enable access to all devices on the host as well as set some configuration in AppArmor or SELinux to allow the container nearly all the same access to the host as processes running outside containers on the host. Additional information about running with —privileged is available on the Docker Blog
If you want to limit access to a specific device or devices you can use the —device flag. It allows you to specify one or more devices that will be accessible within the container.
By default, the container will be able to read , write , and mknod these devices. This can be overridden using a third :rwm set of options to each —device flag:
In addition to —privileged , the operator can have fine grain control over the capabilities using —cap-add and —cap-drop . By default, Docker has a default list of capabilities that are kept. The following table lists the Linux capability options which are allowed by default and can be dropped.
| Capability Key | Capability Description |
|---|---|
| AUDIT_WRITE | Write records to kernel auditing log. |
| CHOWN | Make arbitrary changes to file UIDs and GIDs (see chown(2)). |
| DAC_OVERRIDE | Bypass file read, write, and execute permission checks. |
| FOWNER | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. |
| FSETID | Don’t clear set-user-ID and set-group-ID permission bits when a file is modified. |
| KILL | Bypass permission checks for sending signals. |
| MKNOD | Create special files using mknod(2). |
| NET_BIND_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024). |
| NET_RAW | Use RAW and PACKET sockets. |
| SETFCAP | Set file capabilities. |
| SETGID | Make arbitrary manipulations of process GIDs and supplementary GID list. |
| SETPCAP | Modify process capabilities. |
| SETUID | Make arbitrary manipulations of process UIDs. |
| SYS_CHROOT | Use chroot(2), change root directory. |
The next table shows the capabilities which are not granted by default and may be added.
| Capability Key | Capability Description |
|---|---|
| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. |
| AUDIT_READ | Allow reading the audit log via multicast netlink socket. |
| BLOCK_SUSPEND | Allow preventing system suspends. |
| BPF | Allow creating BPF maps, loading BPF Type Format (BTF) data, retrieve JITed code of BPF programs, and more. |
| CHECKPOINT_RESTORE | Allow checkpoint/restore related operations. Introduced in kernel 5.9. |
| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. |
| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). |
| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. |
| LEASE | Establish leases on arbitrary files (see fcntl(2)). |
| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. |
| MAC_ADMIN | Allow MAC configuration or state changes. Implemented for the Smack LSM. |
| MAC_OVERRIDE | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). |
| NET_ADMIN | Perform various network-related operations. |
| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. |
| PERFMON | Allow system performance and observability privileged operations using perf_events, i915_perf and other kernel subsystems |
| SYS_ADMIN | Perform a range of system administration operations. |
| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. |
| SYS_MODULE | Load and unload kernel modules. |
| SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. |
| SYS_PACCT | Use acct(2), switch process accounting on or off. |
| SYS_PTRACE | Trace arbitrary processes using ptrace(2). |
| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). |
| SYS_RESOURCE | Override resource Limits. |
| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. |
| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. |
| SYSLOG | Perform privileged syslog(2) operations. |
| WAKE_ALARM | Trigger something that will wake up the system. |
Further reference information is available on the capabilities(7) — Linux man page
Both flags support the value ALL , so to allow a container to use all capabilities except for MKNOD :
The —cap-add and —cap-drop flags accept capabilities to be specified with a CAP_ prefix. The following examples are therefore equivalent:
For interacting with the network stack, instead of using —privileged they should use —cap-add=NET_ADMIN to modify the network interfaces.
To mount a FUSE based filesystem, you need to combine both —cap-add and —device :
The default seccomp profile will adjust to the selected capabilities, in order to allow use of facilities allowed by the capabilities, so you should not have to adjust this.
Overriding image defaults
When you build an image from a Dockerfile
, or when committing it, you can set a number of default parameters that take effect when the image starts up as a container. When you run an image, you can override those defaults using flags for the docker run command.
- Default entrypoint
- Default command and options
- Expose ports
- Environment variables
- Healthcheck
- User
- Working directory
Default command and options
The command syntax for docker run supports optionally specifying commands and arguments to the container’s entrypoint, represented as [COMMAND] and [ARG. ] in the following synopsis example:
This command is optional because whoever created the IMAGE may have already provided a default COMMAND , using the Dockerfile CMD instruction. When you run a container, you can override that CMD instruction just by specifying a new COMMAND .
If the image also specifies an ENTRYPOINT then the CMD or COMMAND get appended as arguments to the ENTRYPOINT .
Default entrypoint
The entrypoint refers to the default executable that’s invoked when you run a container. A container’s entrypoint is defined using the Dockerfile ENTRYPOINT instruction. It’s similar to specifying a default command because it specifies, but the difference is that you need to pass an explicit flag to override the entrypoint, whereas you can override default commands with positional arguments. The defines a container’s default behavior, with the idea that when you set an entrypoint you can run the container as if it were that binary, complete with default options, and you can pass in more options as commands. But there are cases where you may want to run something else inside the container. This is when overriding the default entrypoint at runtime comes in handy, using the —entrypoint flag for the docker run command.
The —entrypoint flag expects a string value, representing the name or path of the binary that you want to invoke when the container starts. The following example shows you how to run a Bash shell in a container that has been set up to automatically run some other binary (like /usr/bin/redis-server ):
The following examples show how to pass additional parameters to the custom entrypoint, using the positional command arguments:
You can reset a containers entrypoint by passing an empty string, for example:
Note
Passing —entrypoint clears out any default command set on the image. That is, any CMD instruction in the Dockerfile used to build it.
Exposed ports
By default, when you run a container, none of the container’s ports are exposed to the host. This means you won’t be able to access any ports that the container might be listening on. To make a container’s ports accessible from the host, you need to publish the ports.
You can start the container with the -P or -p flags to expose its ports:
- The -P (or —publish-all ) flag publishes all the exposed ports to the host. Docker binds each exposed port to a random port on the host. The -P flag only publishes port numbers that are explicitly flagged as exposed, either using the Dockerfile EXPOSE instruction or the —expose flag for the docker run command.
- The -p (or —publish ) flag lets you explicitly map a single port or range of ports in the container to the host.
The port number inside the container (where the service listens) doesn’t need to match the port number published on the outside of the container (where clients connect). For example, inside the container an HTTP service might be listening on port 80. At runtime, the port might be bound to 42800 on the host. To find the mapping between the host ports and the exposed ports, use the docker port command.
Environment variables
Docker automatically sets some environment variables when creating a Linux container. Docker doesn’t set any environment variables when creating a Windows container.
The following environment variables are set for Linux containers:
| Variable | Value |
|---|---|
| HOME | Set based on the value of USER |
| HOSTNAME | The hostname associated with the container |
| PATH | Includes popular directories, such as /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin |
| TERM | xterm if the container is allocated a pseudo-TTY |
Additionally, you can set any environment variable in the container by using one or more -e flags. You can even override the variables mentioned above, or variables defined using a Dockerfile ENV instruction when building the image.
If the you name an environment variable without specifying a value, the current value of the named variable on the host is propagated into the container’s environment:
The following flags for the docker run command let you control the parameters for container healthchecks:
| Option | Description |
|---|---|
| —health-cmd | Command to run to check health |
| —health-interval | Time between running the check |
| —health-retries | Consecutive failures needed to report unhealthy |
| —health-timeout | Maximum time to allow one check to run |
| —health-start-period | Start period for the container to initialize before starting health-retries countdown |
| —health-start-interval | Time between running the check during the start period |
| —no-healthcheck | Disable any container-specified HEALTHCHECK |
>' , , , , The health status is also displayed in the docker ps output.
User
The default user within a container is root (uid = 0). You can set a default user to run the first process with the Dockerfile USER instruction. When starting a container, you can override the USER instruction by passing the -u option.
The followings examples are all valid:
Как работает протокол X11 на самом нижнем уровне
X11 это тот механизм на чем работает весь графический интерфейс Unix подобных ОС.
Но мало кто знает как он работает на самом деле. Потому что с годами он оброс слоями и слоями библиотек, которые стремятся скрыть саму сущность протокола.
А протокол в своей сути прекрасен. Он лаконичен и почти совершенен.
В Интернете есть полная документация по протоколу. Но дело в том, что эта документация большая, написана не совсем ясным языком и, по сути, является просто спецификацией. Важные моменты никак не обозначены, а как использовать – тоже оставлено на фантазию читателя.
А все книги и статьи по использованию X11 описывают это через библиотеки прокладки типа XLib и XCB, и даже, что хуже, GTK или Qt.
Так что документацию приходится читать всю и самому выделять что важно, а что не очень. Придумывать сценарии использования и писать хотя бы короткие программы чтобы испробовать как все работает на самом деле.
Как бы то ни было, если кому-то интересно как все работает на самом деле, пожалуйста под кат.
Суть
Суть X11 в том, что есть программа сервер (X server) которая ожидает подключения и выполняет те команды которые получает от клиента. Например, создать графическое окно. Нарисовать что-то и так далее.
Клиенты подключаются к серверу через обычный сокет. Посылают команды и получают обратно ответы, ошибки, если что-то пошло не так, а также события (например перемещения мыши, нажимания на кнопки и т.п.)
Клиент, по сути это консольная программа, которая с графикой не имеет ничего общего, кроме этого сетевого соединения.
Протокол
Весь основной протокол описан в документе X Window System Protocol
Самое полезное в этом документе, это приложение «B», где описано побайтно, что и куда присылается и принимается.
Я буду цитировать отрывки, чтобы иллюстрировать текст.
Идентификаторы
Все объекты в X имеют идентификатор. Это 32 битовое число, которое генерирует клиент и передает серверу, чтобы обозначить создаваемый объект. Например, окно, курсор, картинка и т.д.
Другой тип идентификаторов это ATOM. Атомы это тоже 32 битовые числа, но их генерирует сервер. Клиент передает серверу какую-то символьную строку, а сервер в ответ дает число. Одинаковым строкам всегда соответствует одинаковое число. Это похоже на хеширование, но сделано по другому – сервер просто хранит список строк и присваивает им номера. Если какой-то клиент запросит атом для строки которая уже находится в списке, ему возвращают номер строки в списке.
Атомы используются прежде всего, чтобы разные клиенты могли обмениваться информацией друг с другом, используя стандартные текстовые идентификаторы.
А чтобы не грузить сетевой обмен длинными текстовыми идентификаторами, передаются собственно числа.
Чтобы снизить нагрузку на сервер, самые важные атомы определены в стандарте и всегда имеют одни и те же значения. Если кому-то интересно, список здесь:
Стандартные атомы
То что написано большими буквами, является той строкой из которой генерирован атом:
atomPRIMARY = 1 atomSECONDARY = 2 atomARC = 3 atomATOM = 4 atomBITMAP = 5 atomCARDINAL = 6 atomCOLORMAP = 7 atomCURSOR = 8 atomCUT_BUFFER0 = 9 atomCUT_BUFFER1 = 10 atomCUT_BUFFER2 = 11 atomCUT_BUFFER3 = 12 atomCUT_BUFFER4 = 13 atomCUT_BUFFER5 = 14 atomCUT_BUFFER6 = 15 atomCUT_BUFFER7 = 16 atomDRAWABLE = 17 atomFONT = 18 atomINTEGER = 19 atomPIXMAP = 20 atomPOINT = 21 atomRECTANGLE = 22 atomRESOURCE_MANAGER = 23 atomRGB_COLOR_MAP = 24 atomRGB_BEST_MAP = 25 atomRGB_BLUE_MAP = 26 atomRGB_DEFAULT_MAP = 27 atomRGB_GRAY_MAP = 28 atomRGB_GREEN_MAP = 29 atomRGB_RED_MAP = 30 atomSTRING = 31 atomVISUALID = 32 atomWINDOW = 33 atomWM_COMMAND = 34 atomWM_HINTS = 35 atomWM_CLIENT_MACHINE = 36 atomWM_ICON_NAME = 37 atomWM_ICON_SIZE = 38 atomWM_NAME = 39 atomWM_NORMAL_HINTS = 40 atomWM_SIZE_HINTS = 41 atomWM_ZOOM_HINTS = 42 atomMIN_SPACE = 43 atomNORM_SPACE = 44 atomMAX_SPACE = 45 atomEND_SPACE = 46 atomSUPERSCRIPT_X = 47 atomSUPERSCRIPT_Y = 48 atomSUBSCRIPT_X = 49 atomSUBSCRIPT_Y = 50 atomUNDERLINE_POSITION = 51 atomUNDERLINE_THICKNESS= 52 atomSTRIKEOUT_ASCENT = 53 atomSTRIKEOUT_DESCENT = 54 atomITALIC_ANGLE = 55 atomX_HEIGHT = 56 atomQUAD_WIDTH = 57 atomWEIGHT = 58 atomPOINT_SIZE = 59 atomRESOLUTION = 60 atomCOPYRIGHT = 61 atomNOTICE = 62 atomFONT_NAME = 63 atomFAMILY_NAME = 64 atomFULL_NAME = 65 atomCAP_HEIGHT = 66 atomWM_CLASS = 67 atomWM_TRANSIENT_FOR = 68Запросы
Все запросы в X11 бинарные, с полями разной длины. По сути, здесь есть поля длиной в 1 байт, 2 байта и 4 байта.
Первые 4 байта запроса всегда присутствуют и всегда содержат одинаковую информацию:
| Смещение | Длина | Содержание |
|---|---|---|
| 0 | 1 | Код команды. Основной протокол использует только значения от 1 до 127, а значения больше 127 выделены расширениям. |
| 1 | 1 | Подкоманда или какой-то параметр запроса длиной в 1 байт или не используется. |
| 2 | 2 | Длина всего запроса в двойных словах (4 байта). |
Прочтя этот заголовок, сервер уже знает сколько байт (а точнее двойных слов) еще надо прочесть, чтобы забрать весь запрос.
Чтобы не быть слишком голословным покажу простой пример:
Запрос «DestroyWindow» кодируется вот так (допустим хотим закрыть окно с ID 0x12345678):
| Смещение | Длина | Значение | Заметки |
|---|---|---|---|
| 0 | 1 | 0x03 | 3 это код операции DestroyWindow |
| 1 | 1 | 0x00 | Не используется. Значение может быть любое. Сервер все-равно его не смотрит. |
| 2 | 2 | 0x0002 | Длина запроса 2 двойных слова или 8 байт. |
| 4 | 4 | 0x12345678 | Идентификатор окна. |
Или в итоге, по сокету уходит вот что: 03 00 02 00 78 56 34 12
Получив этот запрос, X сервер закроет окно с идентификатором 0x12345678
В документации протокола (а точнее в приложении), вот это запрос DestroyWindow описан следующим синтаксисом:
1 4 opcode 1 unused 2 2 request length 4 WINDOW window
А сейчас что-то посложнее: «CreateWindow».
Предварительно надо выбрать идентификатор окна. Выберем опять 0x12345678 чтобы было попроще.
Еще понадобиться идентификатор коренного окна (это служебное окно, которое занимает весь дисплей и является родительским для всех окон верхнего уровня). Допустим его идентификатор 0x9abcdef0 (а откуда взять реальные значения, я расскажу немножко позже).
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | opcode | 0x01 | Операция CreateWindow == 1 |
| 1 | 1 | depth | 0x00 | Глубина цвета окна. 0 значит CopyFromParent |
| 2 | 2 | length | 0x0008 | |
| 4 | 4 | wid | 0x12345678 | Идентификатор, который выбрали. |
| 8 | 4 | parent | 0x9abcdef0 | |
| 12 | 2 | x | 0x64 | Это X координата верхнего левого угла нашего окна. |
| 14 | 2 | y | 0x65 | Это Y координата окна. |
| 16 | 2 | width | 0xc8 | Ширина окна. |
| 18 | 2 | height | 0x66 | Высота окна. |
| 20 | 2 | border | 0x0000 | Ширина рамки окна. |
| 22 | 2 | class | 0x0001 | 1 это окно InputOutput. Есть и InputOnly, но они слишком специфические (да и не окна по сути) и их не будем рассматривать здесь. |
| 24 | 4 | visual | 0x00000000 | 0 значит скопировать из родителя. Visual это какое-то абстрактное представление экрана в котором я так и не разобрался. Но CopyFromParent работает всегда. 😉 |
| 28 | 4 | value_mask | 0x00000000 | Здесь кончается фиксированная часть запроса. (длиной в 8 двойных словах). Если нужно, можно задать дополнительные параметры окна. Для этого нужно в value_mask поставить единицы в некоторые биты, поставить необходимые параметры после 32го байта запроса и соответственно увеличить длины запроса в поле length на нужное число двойных слов. |
И так, итоговый запрос который отправляем на сокет: 01 00 08 00 78 65 43 21 f0 de bc 9a 64 65 c8 66 00 00 01 00 00 00 00 00 00 00 00 00
Вот и полное описание запроса в приложении протокола:
1 1 opcode 1 CARD8 depth 2 8+n request length 4 WINDOW wid 4 WINDOW parent 2 INT16 x 2 INT16 y 2 CARD16 width 2 CARD16 height 2 CARD16 border-width 2 class 0 CopyFromParent 1 InputOutput 2 InputOnly 4 VISUALID visual 0 CopyFromParent 4 BITMASK value-mask (has n bits set to 1) #x00000001 background-pixmap #x00000002 background-pixel #x00000004 border-pixmap #x00000008 border-pixel #x00000010 bit-gravity #x00000020 win-gravity #x00000040 backing-store #x00000080 backing-planes #x00000100 backing-pixel #x00000200 override-redirect #x00000400 save-under #x00000800 event-mask #x00001000 do-not-propagate-mask #x00002000 colormap #x00004000 cursor 4n LISTofVALUE value-list VALUEs 4 PIXMAP background-pixmap 0 None 1 ParentRelative 4 CARD32 background-pixel 4 PIXMAP border-pixmap 0 CopyFromParent 4 CARD32 border-pixel 1 BITGRAVITY bit-gravity 1 WINGRAVITY win-gravity 1 backing-store 0 NotUseful 1 WhenMapped 2 Always 4 CARD32 backing-planes 4 CARD32 backing-pixel 1 BOOL override-redirect 1 BOOL save-under 4 SETofEVENT event-mask 4 SETofDEVICEEVENT do-not-propagate-mask 4 COLORMAP colormap 0 CopyFromParent 4 CURSOR cursor 0 None
Немножко сложнее, но надеюсь более-менее понятно… Сложность здесь из-за того, что в запросе можно передать кучу параметров окна разного вида и формата. Но по сути все идет последовательно и более-менее логично.
После получения этого запроса, сервер создает окно с заданными параметрами. Но это окно не появится, так как все еще не показано на экране. Делаем это через запрос «MapWindow». На фоне прежнего, он совсем простенький:
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | opcode | 0x08 | Операция MapWindow == 8 |
| 1 | 1 | 0x00 | Не используется | |
| 2 | 2 | length | 0x0002 | Длина 8 байт. |
| 4 | 4 | wid | 0x12345678 | Это ID нашего окна. |
На сокет уходит: 08 00 02 00 78 56 34 12 а окно становится видным.
Ответы
Сервер тоже присылает нам по сокету информацию. Она бывает 3 вида: Ответы (Reply), События (Events) и Ошибки (Errors).
Все три вида имеют длину минимум 32 байта. (А события и ошибки всегда точно 32 байта). Так что чтение из сервера происходит всегда порциями в 32 байта и если это Reply из тела ответа берем длину дополнительной части и читаем ее тоже.
Вся информация с сервера приходит асинхронно, но ответы и ошибки всегда приходят в порядке запросов чьими результатами они являются.
- Ответы на запросы (Reply). Если запрос предполагает ответ от сервера, то сервер его присылает по сокету, как только обработает запрос. Если ответ содержит информацию, которая помещается в 32 байта, то это все что нужно принять. Если ответ длиннее, то в его теле содержится длина дополнительной части ответа.
Общий формат ответа такой:
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | code | 1 | 1 == Reply |
| 1 | 1 | ? | ? | Или не используется, или используется для какой-то части ответа, длиной в 1 байт. |
| 2 | 2 | sequence | s | Это номер запроса, на котором ответ. |
| 4 | 4 | length | n | Длина ответа сверх первых 32 байта в двойных словах. Если не 0, то надо прочитать с сокета еще 4*n байта, чтобы взять весь ответ. |
- События (Events). Содержат те же 32 байта и генерируются в ответ на какие-то события в GUI. Чтобы получать некоторые события, клиент должен подписаться на них, когда создает окно, например.
Некоторые события общесистемного характера присылаются всегда и всем.
Формат событий такой:
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | code | 2..127 [+128] | > 1 для событий. Если событие прислано от другого клиента через SendEvent, то к номеру события прибавляется 128. (Старший бит устанавливается в 1). |
| 1 | 1 | detail | ? | Деталь о событии если помещается в 1 байт. |
| 2 | 2 | sequence | ? | Номер запроса, после которого случилось событие. |
| 4 | 4 | timestamp | time | Время возникновения события |
| 8 | 24 | ? | Зависят от события. |
- Ошибки. Присылаются если какой-то запрос клиента нельзя было исполнить потому что содержит какую-то ошибку в данных или параметрах. Формат ошибок такой:
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | code | 0 | 0 == Error |
| 1 | 1 | error code | 1..255 | Код ошибки. |
| 2 | 2 | sequence | ? | Номер ошибочного запроса. |
| 4 | 28 | data | ? | Подробности об ошибке. Зависит от кода ошибки. |
Подключение.
А сейчас сделаем шаг назад и рассмотрим наверное самое сложное в X11 – подключение к серверу. К сожалению процедура сложная и запутанная и является камнем преткновения для прямого использования X11.
Именно подключение поднимает уровень вхождения в технологию.
Как мы увидели само использование протокола достаточно просто. Но подключение – это что-то с чем-то!
Само подключение по сути простое – создаем сокет и выполняем connect на него. Но сперва надо узнать адрес сервера. Для этого есть алгоритм:
Смотрим на содержание переменной окружения DISPLAY . Если существует, она содержит адрес X11 сервера в формате: [host]:D.S .
host – это хост сервера. Это может быть имя домейна, может быть строкой «/unix» или просто отсутствовать. Отсутствующий host равен «/unix» и означает что сервер слушает на unix domain сокете на локальной машине.
Кстати, это самый частый случай. Если host присутствует, это значит что подключаться надо к этому хосту, по TCP, через IPv6 адрес.
D это номер дисплея, а S это номер экрана. В большинстве случаев на современных конфигурациях номер экрана будет 0, даже если мониторов больше одного. Все они виртуально объединены в один экран.
От номера дисплея зависит порт подключения к серверу. Если по TCP, то сервер слушает на порт 6000+D. Если подключаемся через unix domain сокет, он находится по адресу /tmp/.X11-unix/X – то есть, нулевой дисплей на /tmp/.X11-unix/X0 , первый на /tmp/.X11-unix/X1 и т.д.
И вот, мы подключились к сокету. После подключения, нельзя просто так посылать запросы. Надо сперва отправить на сервер информацию о себе и авторизоваться на сервере.
Все это содержится в первом (а точнее нулевом) запросе, который нестандартный и содержит:
| Смещение | Длина | Имя поля | Значение | Заметки |
|---|---|---|---|---|
| 0 | 1 | byte_order | «B» или «l» | B (0x42) означает BIG-ENDIAN, a «l»(0x6c) – little-endian. |
| 1 | 1 | 0x00 | Не используется | |
| 2 | 2 | major_ver | 11 | Мажорная версия протокола |
| 4 | 2 | minor_ver | 0 | Минорная версия протокола |
| 6 | 2 | auth_proto_len | n | Длина имя протокола авторизации |
| 8 | 2 | auth_data_len | d | Длина данных авторизации |
| 10 | 2 | not_used | ? | Выравнивание |
| 12 | n | auth_proto | string | Протокол авторизации |
| 12+n | pad(n) | Выравнивание к двойному слову. | ||
| 12+n+pad(n) | d | auth_data | string | Данные авторизации |
| 12+n+pad(n)+d | pad(d) | Выравнивание к двойному слову. |
Первый байт определяет в каком формате наша программа понимает числа. Сервер будет присылать нам все числа длиннее одного байта в этом формате и будет понимать числа которые мы присылаем в этом формате.
Потом следует минимальная версия протокола, которая подошла бы программе. Если сервер поддерживает версию ниже этой, то подключение будет отклонено.
Потом следует имя протокола авторизации и собственно данные авторизации. Это типа доказательство, что эта программа имеет право подключаться к серверу X11.
Откуда берем имя протокола и данные об авторизации? Они находятся в файле, путь к которому находится в переменной окружения $XAUTHORITY . Если эта переменная не существует можно поискать в файле $HOME/.Xauthority – это самый распространенный вариант. Если у вашего приложения нет прав доступа к этому файлу или файл не существует, то значит у вас нет доступа к этому X11 серверу.
Файл бинарный и его формат не слишком хорошо задокументирован. Мне пришлось спрашивать на stackoverflow чтобы разобраться, да и то получилось лишь частично.
Так, структура файла, это последовательность записей вот таких структур:
typedef struct xauth < unsigned short family; unsigned short address_length; char *address; unsigned short number_length; char *number; unsigned short name_length; char *name; unsigned short data_length; char *data; >Xauth;Но во первых, в файле, конечно указателей нет. Все строки вписаны просто последовательно, символ за символом в файле. Во вторых – все двухбайтовые числа всегда являются big-endian. Вне зависимости от архитектуры компьютера.
address – это HOST адрес сервера.
number – это номер дисплея, который мы уже определили из переменной $DISPLAY, записанный в виде текстовой строки!
name – это имя протокола. В настоящем времени и насколько я знаю, используется только MIT-MAGIC-COOKIE-1 протокол.
data – это массив байтов, примерно вот такой: 07 bd 70 26 1а ab 4c 7c 35 3c c1 b2 cc 25 a2 29 . который мы должны переслать серверу в знак, что у нас доступ позволен.
Перебираем этот файл пока не найдем запись, у которой HOST совпадает с хостом из $DISPLAY и номер дисплея с номером дисплея из $DISPLAY. Из этой записи достаем имя протокола и данные авторизации.
И так мы собрали все необходимые данные о нулевом запросе и формируем его:
| Смещение | Длина | Имя поля | Байты | Пояснение |
|---|---|---|---|---|
| 0 | 1 | byte_order | 0x6c | l |
| 1 | 1 | 0x00 | ||
| 2 | 2 | major_ver | 0x0b 0x00 | 0x000b |
| 4 | 2 | minor_ver | 0x00 0x00 | 0x0000 |
| 6 | 2 | auth_proto_len | 0x12 | length(«MIT-MAGIC-COOKIE-1») = 18 |
| 8 | 2 | auth_data_len | 0x10 | length(cookie) = 16 |
| 10 | 2 | 0x00 0x00 | не используется. Просто выравнивает. | |
| 12 | 18 | auth_proto | 4d 49 54 2d 4d 41 47 49 43 2d 43 4f 4f 4b 49 45 2d 31 | «MIT-MAGIC-COOKIE-1» |
| 30 | 2 | pad(0x12) | 0x00 0x00 | Выравниваем до 20. |
| 32 | 16 | auth_data | 07 bd 70 26 1а ab 4c 7c 35 3c c1 b2 cc 25 a2 29 |
К серверу уходит: 6c 00 0b 00 00 00 12 00 10 00 00 00 4d 49 54 2d 4d 41 47 49 43 2d 43 4f 4f 4b 49 45 2d 31 00 00 07 bd 70 26 1а ab 4c 7c 35 3c c1 b2 cc 25 a2 29 – всего 48 байтов.
На что сервер может ответить тремя возможными ответами. Вариант ответа определяется по первому байту. Он может быть:
0: Подключение отклонено. Весь ответ содержит:
| Смещение | Длина | Имя поля | Байты | Пояснение |
|---|---|---|---|---|
| 0 | 1 | reply | 0x00 | Failed |
| 1 | 1 | n | n | Длина текстового ответа. |
| 2 | 2 | major_ver | 0x0b 0x00 | Мажорная версия протокола. |
| 4 | 2 | minor_ver | 0x00 0x00 | Минорная версия протокола. |
| 6 | 2 | data_len | (n+p)/4 | Длина дополнительной информации в двойных словах. |
| 8 | n | data | Какое-то текстовое сообщение об ошибке. | |
| 8+n | p | pad(n) | Выравнивание до двойного слова. |
2: Нужна дополнительная аутентификация. Я этого варианта не изучал потому что так и не успел найти систему, которая так бы отвечала…
1: Подключение принято.
Самый хороший для нас вариант. Ответ очень длинный и сложный, содержит главные параметры системы, которые мы должны запомнить и использовать позже в наших запросах.
Я так и не смог нарисовать такую сложную табличку, чтобы все разложить по полочкам. Поэтому вот вам описания ответа из документации протокола:
1 1 Success 1 unused 2 CARD16 protocol-major-version 2 CARD16 protocol-minor-version 2 8+2n+(v+p+m)/4 length in 4-byte units of "additional data" 4 CARD32 release-number 4 CARD32 resource-id-base 4 CARD32 resource-id-mask 4 CARD32 motion-buffer-size 2 v length of vendor 2 CARD16 maximum-request-length 1 CARD8 number of SCREENs in roots 1 n number for FORMATs in pixmap-formats 1 image-byte-order 0 LSBFirst 1 MSBFirst 1 bitmap-format-bit-order 0 LeastSignificant 1 MostSignificant 1 CARD8 bitmap-format-scanline-unit 1 CARD8 bitmap-format-scanline-pad 1 KEYCODE min-keycode 1 KEYCODE max-keycode 4 unused v STRING8 vendor p unused, p=pad(v) 8n LISTofFORMAT pixmap-formats m LISTofSCREEN roots (m is always a multiple of 4) FORMAT 1 CARD8 depth 1 CARD8 bits-per-pixel 1 CARD8 scanline-pad 5 unused SCREEN 4 WINDOW root 4 COLORMAP default-colormap 4 CARD32 white-pixel 4 CARD32 black-pixel 4 SETofEVENT current-input-masks 2 CARD16 width-in-pixels 2 CARD16 height-in-pixels 2 CARD16 width-in-millimeters 2 CARD16 height-in-millimeters 2 CARD16 min-installed-maps 2 CARD16 max-installed-maps 4 VISUALID root-visual 1 backing-stores 0 Never 1 WhenMapped 2 Always 1 BOOL save-unders 1 CARD8 root-depth 1 CARD8 number of DEPTHs in allowed-depths n LISTofDEPTH allowed-depths (n is always a multiple of 4) DEPTH 1 CARD8 depth 1 unused 2 n number of VISUALTYPES in visuals 4 unused 24n LISTofVISUALTYPE visuals VISUALTYPE 4 VISUALID visual-id 1 class 0 StaticGray 1 GrayScale 2 StaticColor 3 PseudoColor 4 TrueColor 5 DirectColor 1 CARD8 bits-per-rgb-value 2 CARD16 colormap-entries 4 CARD32 red-mask 4 CARD32 green-mask 4 CARD32 blue-mask 4 unused
Но как бы и сложным это не выглядело бы, всю информацию не надо запоминать или даже анализировать.
Мы от этого ответа возьмем только то, что важно для нас. И это во первых два числа из полей: resource-id-base и resource-id-mask . Они дают нам диапазон в котором надо генерировать ID константы для всех объектов GUI. (Не забывайте, что в X11 все идентификаторы объектов генерируются на стороне клиента, а серверу именно клиент говорит какой будет ID окна или других объектов.)
Так, у сервера есть только одно ограничение – каждой программе он выделяет диапазон в котором идентификаторы должны помещаться. Так идентификатор должен содержать только те биты которые в resource-id-mask установлены в единицу. И идентификатор должен начинать с resource-id_base.
Еще надо запомнить для будущего использования диапазон клавиатурных кодов (min-keycode/max-keycode), найти в ответе те форматы изображений, которые программа может использовать и которые ей удобны.
Еще обязательно надо найти подходящий SCREEN из списка и оттуда взять идентификатор коренного окна. Он нам нужен, в качестве родительского окна для всех окон верхнего уровня, которые мы будем создавать.
Все остальное более или менее можно проигнорировать.
Я обычно ищу во всем этом многообразии тот SCREEN, который меня устраивает (32 бит TrueColor) и использую только его. А если сервер такое не поддерживает, просто заканчиваю работу. Это сильно упрощает работу и код.
Заключение
Ну это все для первого раза. Надеюсь сумел все объяснить яснее чем в документации и дать то понимание, которое позволит дальше свободно читать документацию (А она и правда хороша, если человек умеет ее понимать).
В качестве упражнения предлагаю конкурс-челендж: Написать программу на bash которая устанавливает соединение с X сервером и создает и показывает окно с заголовком «X11 rules».
Если никто не справится или не захочет, я попробую написать ее в качестве примера для следующей статьи цикла.
Спрашивайте в комментариях если что не ясно. Если что не нравиться тоже пишите. Статья может и будет редактироваться по мере обсуждения.
Saved searches
Use saved searches to filter your results more quickly
Cancel Create saved search
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.
xtermjs / xterm.js Public
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
wrap issue when prompt is over 2 lines #2752
adamjimenez opened this issue Mar 9, 2020 · 27 comments
wrap issue when prompt is over 2 lines #2752
adamjimenez opened this issue Mar 9, 2020 · 27 comments
Comments
adamjimenez commented Mar 9, 2020
The cursor positioning is off when backspacing if the prompt is over two lines:
Also is there a way to remove the path from the prompt?
The text was updated successfully, but these errors were encountered:
Tyriar added the needs more info label Mar 9, 2020
adamjimenez commented Mar 9, 2020 via email
own program
— Best regards, Adam Jimenez
jerch commented Mar 9, 2020
Backspacing into previous line? This should not be possible at all until #2724 has landed and got activated by an explicit CSI command.
@adamjimenez Can you give abit more context, how you set up xterm.js?
adamjimenez commented Mar 10, 2020
I’m using xterm in ShiftEdit. The back-end is provided by ttyx.
jerch commented Mar 10, 2020 •
@adamjimenez Looking at your code in https://github.com/adamjimenez/shiftedit/blob/fb218169a4e323e78697887ecbfb70fe43ff31f1/app/ssh.js#L182 I wonder what that custom key handler is used for? Normally you dont have to deal with any key overrides yourself, xterm.js handles that for you and you can simply work with data from onData . Not sure if this code is related to the issue.
Thats way outdated, plz consider upgrading to a newer version. xterm.js is a volunteer project, thus we cannot provide LTS for old release.
Back on the issue at hand:
There must be some code that is responsible for the cursor move into the previous line. Start digging there (a wild guess — that code might wrongly account EOL chars \r\n into offset calculation). xterm.js does not support backspacing into previous lines (yet).
adamjimenez commented Mar 10, 2020
@jerch The reason for the custom key handler is to handle multiple instances so that the data is passed to the correct instance.
I’ve updated to xterm@4.0.2 and am seeing a similar pattern of behaviour when the prompt wraps onto three lines.
BTW thanks for the support, the fact that you dug into my repo to help me out speaks volumes ��
jerch commented Mar 10, 2020 •
Oh well, I overlooked that — so you only see this, if its a shell prompt over several lines? Thats an important bit of info, because shells are smarter in line processing and actually move the cursor around.
Can you switch the log level to ‘debug’ ( new Terminal() ) and post the console.log here? Also check if the pty and the terminal have the same size when this happens. Furthermore — does this only happen after resize or always (we have a known race condition in resize which tends to trigger for overlong shell prompts)?
adamjimenez commented Mar 11, 2020
Yes, it does appear to have something to do with the shell prompt.
I’ve enabled logs and captured this recording:
It happens with or without resize.
jerch commented Mar 11, 2020 •
@adamjimenez Yes, sadly that is a known race condition we cannot do much about currently as it needs a fundamental rewrite of the resize cycling and propagation between xterm.js and the pty/process. Furthermore, even with this rewrite we cannot completely avoid it, and the rewrite would introduce pretty bad delay during resizing. So its not yet clear how even a partial fix should look like.
@Tyriar Were there some recent changes regarding this? Seems we get more often issue reports now?
jerch commented Mar 11, 2020
@adamjimenez Did some further tests with other emulators and different shells. For me this faulty behavior is always reproducible with bash in any emulator (tested gnome-terminal, xterm, konsole, rxvt): as soon as the prompt content hits the third line, it goes all bonkers. No matter if there is pending input behind or not. Which actually makes me think, that it might be a bug in bashs prompt refreshing? Are you using bash by any chance? Also note that I cannot repro it with zsh. Tested on Ubuntu 18 LTS with bash v4.4.20.
adamjimenez commented Mar 12, 2020
Thanks for digging into this. Can confirm, I’m also on Ubuntu 18LTS with bash v4.4.20
jerch commented Mar 12, 2020 •
This issue reveals a zoo of quirks and broken workarounds. On both ends, xterm.js and shells.
Did some further tests with bash and zsh, all were done with a clean longish PS1 string containing only ‘a’. This is needed to avoid runwidth calc errors in libreadline, more on this below.
Results:
Currently all shells redraw their prompt on their own after a resize. For this they all rely on the old resize behavior w’o reflowing, thus they think the cursor is stable in terms of rows and would only change col offset. From this assumption they calc the needed area to be cleaned up to the beginning of the prompt, and basically redraw the whole prompt.
Problem1:
@Tyriar was aware of that problem and kinda implemented a «sticky» rule in the reflow algo, that would reflow all bufferlines, except the last ones joined by isWrapped (where the cursor is?), which would follow the old resize logic. This is error prone on its own, but works most of the time, if the cursor is indeed in a shell prompt line. Still this will break the cursor line in any non shell REPL, that does not redraw that screen part on resize. (@Tyriar plz correct me, if I put it the wrong way. )
Problem2:
zsh puts a hard linebreak (‘\r\n’) into the prompt line, if the prompt happens to end at the last cell in a row, just to get the cursor at the beginning of the next line. This is toxic for the reflow logic above, as now the sticky rule only applies to that newish row. Solution would be easy on zsh side: instead of doing a hard linebreak, put there a space + BS, which results in the same screen output, but would mark the new row as wrapped, thus count into the sticky part. Btw bash gets this one right.
Problem3:
bash wrongly calcs parts to be deleted, if the prompt filled a row to the last cell, and resize enlarges the viewport. It always misses chars at the end. Weird though, that this only happens, if the last was full. Looking at their cleanup code explains why: seems they send CR EL0 CUU(times wrap) PROMPT , but for a full line the cursor is already at the beginning of the next line, thus they miss erasing the line before, and the prompt overwrites now less cells keeping old stuff in excess cells. Since bash does not mess with hard linebreak, it works otherwise.
Btw the problem mentioned in #2752 (comment) went away with the clean PS1 string. There is something wrong with Ubuntu’s default PS1 line, bash has troubles to correctly calc the runwidth of it. I double checked with the actual printout set hard as PS1 line, which works again.
Solution?
Well, I think a clean solution would be:
- remove the quirks for shell prompts from reflow, thus also reflow the cursor row normally
- announce somehow, whether the terminal does static resize or reflow (env var? DA attribute?), a shell should eval that bit of information and decide, whether to redraw itself or to rely on terminal reflow
Or get the shell extension proposed by @PerBothner done, this way a shell can mark its prompt and we can skip those lines during reflowing more reliably. In any case — both solutions would require the shells to play along. Not even sure if any shell cares for reflow, xterm doesnt have it, so why bothering? 😉
Found an old conversation on the bash mailing list about this (~2016), which also mentioned @egmontkob, but it kinda ended somewhere between the lines «not our fault | cannot do much about it | not sure who to blame», which is not getting us anywhere.