From efda0ea45599d7f00ce076610e4c6552165c551e Mon Sep 17 00:00:00 2001 From: pagedown Date: Tue, 22 Mar 2022 23:25:59 +0800 Subject: [PATCH 1/2] Docs: Categorize the ssh kitten configuration options and minor tweaks --- docs/kittens/ssh.rst | 22 +++++------ kittens/ssh/copy.py | 7 ++-- kittens/ssh/options/definition.py | 62 +++++++++++++++++-------------- 3 files changed, 49 insertions(+), 42 deletions(-) diff --git a/docs/kittens/ssh.rst b/docs/kittens/ssh.rst index 7875a7149..fd783b764 100644 --- a/docs/kittens/ssh.rst +++ b/docs/kittens/ssh.rst @@ -31,7 +31,7 @@ rc files: alias s=kitty +kitten ssh -So you can now type just ``s hostname`` to connect. +So now you can just type ``s hostname`` to connect. If you define a mapping in :file:`kitty.conf` such as:: @@ -76,11 +76,11 @@ from :file:`ssh.conf`. These are merged with :file:`ssh.conf` as if they were appended to the end of that file. They apply only to the host being SSHed to by this invocation, so any :opt:`hostname ` directives are ignored. -.. note:: +.. warning:: - Because of limitations of the design of SSH, any typing you do before the - shell prompt appears may be lost. So ideally dont start typing till you see - the shell prompt 😇. + Due to the limitations in the design of SSH, any typing you do before the + shell prompt appears may be lost. So ideally don't start typing till you see + the shell prompt. 😇 .. _real_world_ssh_kitten_config: @@ -121,12 +121,12 @@ remote server using an :opt:`interpreter `. This script reads setup data over the tty device, which kitty sends as a base64 encoded compressed tarball. The script extracts it and places the :opt:`files ` and sets the :opt:`environment variables ` before finally -launching the :opt:`login shell ` with shell -integration enabled. The data is requested by the kitten over the TTY with a -random one time password. kitty reads the request and if the password matches -a password pre-stored in shared memory on the localhost by the kitten, the -transmission is allowed. If your OpenSSH version is >= 8.4 then the data is -transmitted instantly without any roundtrip delay. +launching the :opt:`login shell ` with :opt:`shell +integration ` enabled. The data is requested by +the kitten over the TTY with a random one time password. kitty reads the request +and if the password matches a password pre-stored in shared memory on the +localhost by the kitten, the transmission is allowed. If your OpenSSH version is +>= 8.4 then the data is transmitted instantly without any roundtrip delay. .. note:: diff --git a/kittens/ssh/copy.py b/kittens/ssh/copy.py index b861b914b..364e0437a 100644 --- a/kittens/ssh/copy.py +++ b/kittens/ssh/copy.py @@ -35,9 +35,10 @@ variables and ~ are not expanded. --exclude type=list -A glob pattern. Files whose names would match this pattern after transfer -are excluded from being transferred. Useful when adding directories. Can -be specified multiple times, if any of the patterns match the file will be excluded. +A glob pattern. Files with names matching this pattern are excluded from being +transferred. Useful when adding directories. Can +be specified multiple times, if any of the patterns match the file will be +excluded. ''' diff --git a/kittens/ssh/options/definition.py b/kittens/ssh/options/definition.py index 0e0ba2fbe..c8fd79579 100644 --- a/kittens/ssh/options/definition.py +++ b/kittens/ssh/options/definition.py @@ -21,11 +21,10 @@ agr = definition.add_group egr = definition.end_group opt = definition.add_option -agr('host', 'Host environment') # {{{ +agr('bootstrap', 'Host bootstrap configuration') # {{{ -opt('hostname', '*', option_type='hostname', - long_text=''' -The hostname the following options apply to. A glob pattern to match multiple +opt('hostname', '*', option_type='hostname', long_text=''' +The hostname that the following options apply to. A glob pattern to match multiple hosts can be used. Multiple hostnames can also be specified separated by spaces. The hostname can include an optional username in the form :code:`user@host`. When not specified options apply to all hosts, until the @@ -35,6 +34,18 @@ If you wish to include the same basic configuration for many different hosts, you can do so with the :ref:`include ` directive. ''') +opt('interpreter', 'sh', long_text=''' +The interpreter to use on the remote host. Must be either a POSIX complaint shell +or a python executable. If the default sh is not available or broken, using +an alternate interpreter can be useful. +''') + +opt('remote_dir', '.local/share/kitty-ssh-kitten', option_type='relative_dir', long_text=''' +The location on the remote computer where the files needed for this kitten +are installed. The location is relative to the HOME directory. Absolute paths or paths +that resolve to a location outside the HOME are not allowed. +''') + opt('+copy', '', option_type='copy', add_to_default=False, long_text=f''' {copy_message} For example:: @@ -56,6 +67,21 @@ Files can be excluded when copying with :code:`--exclude`:: Files whose remote name matches the exclude pattern will not be copied. For more details, see :ref:`ssh_copy_command`. ''') +egr() # }}} + +agr('shell', 'Login shell environment') # {{{ + +opt('shell_integration', 'inherited', long_text=''' +Control the shell integration on the remote host. See :ref:`shell_integration` +for details on how this setting works. The special value :code:`inherited` means +use the setting from :file:`kitty.conf`. This setting is useful for overriding +integration on a per-host basis. +''') + +opt('login_shell', '', long_text=''' +The login shell to execute on the remote host. By default, the remote user account's +login shell is used. +''') opt('+env', '', option_type='env', add_to_default=False, long_text=''' Specify environment variables to set on the remote host. Note that @@ -71,42 +97,22 @@ are processed alphabetically. The special value :code:`_kitty_copy_env_var_` will cause the value of the variable to be copied from the local machine. ''') - opt('cwd', '', long_text=''' The working directory on the remote host to change to. Env vars in this value are expanded. The default is empty so no changing is done, which usually means the home directory is used. ''') +egr() # }}} -opt('share_connections', 'y', option_type='to_bool', long_text=''' +agr('ssh', 'SSH configuration') # {{{ + +opt('share_connections', 'yes', option_type='to_bool', long_text=''' Within a single kitty instance, all connections to a particular server can be shared. This reduces startup latency for subsequent connections and means that you have to enter the password only once. Under the hood, it uses SSH ControlMasters and these are automatically cleaned up by kitty when it quits. ''') -opt('interpreter', 'sh', long_text=''' -The interpreter to use on the remote host. Must be either a POSIX complaint shell -or a python executable. If the default sh is not available or broken, using -an alternate interpreter can be useful. -''') - -opt('remote_dir', '.local/share/kitty-ssh-kitten', option_type='relative_dir', long_text=''' -The location on the remote computer where the files needed for this kitten -are installed. The location is relative to the HOME directory. Absolute paths or paths -that resolve to a location outside the HOME are not allowed. -''') - -opt('shell_integration', 'inherited', long_text=''' -Control the shell integration on the remote host. See :ref:`shell_integration` -for details on how this setting works. The special value :code:`inherited` means -use the setting from :file:`kitty.conf`. This setting is useful for overriding -integration on a per-host basis.''') - -opt('login_shell', '', long_text=''' -The login shell to execute on the remote host. By default, the remote user account's -login shell is used.''') - opt('askpass', 'unless-set', choices=('unless-set', 'ssh', 'native'), long_text=''' Control the program SSH uses to ask for passwords or confirmation of host keys etc. The default is to use kitty's native askpass, unless the SSH_ASKPASS From ff8a99211d5967c670f7657ce8b858960dbb61a3 Mon Sep 17 00:00:00 2001 From: pagedown Date: Tue, 22 Mar 2022 23:26:15 +0800 Subject: [PATCH 2/2] Docs: Unify and generalize the terms remote computer, machine and host --- docs/kittens/ssh.rst | 26 +++++++++++++------------- kittens/ssh/copy.py | 4 ++-- kittens/ssh/options/definition.py | 16 ++++++++-------- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/kittens/ssh.rst b/docs/kittens/ssh.rst index fd783b764..1ffbecbfb 100644 --- a/docs/kittens/ssh.rst +++ b/docs/kittens/ssh.rst @@ -1,18 +1,18 @@ Truly convenient SSH ========================================= -* Automatic :ref:`shell_integration` on remote machines +* Automatic :ref:`shell_integration` on remote hosts -* Easily :ref:`clone local shell/editor config ` on remote machines +* Easily :ref:`clone local shell/editor config ` on remote hosts * Automatic :opt:`re-use of existing connections ` to avoid connection setup latency -The ssh kitten allows you to login easily to remote servers, and automatically +The ssh kitten allows you to login easily to remote hosts, and automatically setup the environment there to be as comfortable as your local shell. You -can specify environment variables to set on the remote server and +can specify environment variables to set on the remote host and files to copy there, making your remote experience just like your local shell. Additionally, it automatically sets up :ref:`shell_integration` on -the remote server and copies the kitty terminfo database there. +the remote host and copies the kitty terminfo database there. The ssh kitten is a thin wrapper around the traditional `ssh `__ command line program and supports all the same options and arguments and configuration. @@ -23,7 +23,7 @@ out, simply run: kitty +kitten ssh some-hostname-to-connect-to -You should end up at a shell prompt on the remote server, with shell +You should end up at a shell prompt on the remote host, with shell integration enabled. If you like it you can add an alias to it in your shell's rc files: @@ -38,11 +38,11 @@ If you define a mapping in :file:`kitty.conf` such as:: map f1 new_window_with_cwd Then, pressing :kbd:`F1` will open a new window automatically logged -into the same server using the ssh kitten, at the same directory. +into the same host using the ssh kitten, at the same directory. The ssh kitten can be configured using the :file:`~/.config/kitty/ssh.conf` -file where you can specify environment variables to set on the remote server -and files to copy from your local machine to the remote server. Let's see a +file where you can specify environment variables to set on the remote host +and files to copy from the local to the remote host. Let's see a quick example: .. code-block:: conf @@ -51,7 +51,7 @@ quick example: copy .zshrc .vimrc .vim # Setup some environment variables env SOME_VAR=x - # COPIED_VAR will have the same value on the remote server as it does locally + # COPIED_VAR will have the same value on the remote host as it does locally env COPIED_VAR=_kitty_copy_env_var_ # Create some per hostname settings @@ -117,7 +117,7 @@ How it works The ssh kitten works by having SSH transmit and execute a POSIX sh (or :opt:`optionally ` Python) bootstrap script on the -remote server using an :opt:`interpreter `. This script +remote host using an :opt:`interpreter `. This script reads setup data over the tty device, which kitty sends as a base64 encoded compressed tarball. The script extracts it and places the :opt:`files ` and sets the :opt:`environment variables ` before finally @@ -130,9 +130,9 @@ localhost by the kitten, the transmission is allowed. If your OpenSSH version is .. note:: - When connecting to BSD servers, it is possible the bootstrap script will + When connecting to BSD hosts, it is possible the bootstrap script will fail or run slowly, because the default shells are crippled in various ways. - Your best bet is to install python on the server, make sure the login shell + Your best bet is to install Python on the remote, make sure the login shell is something POSIX sh compliant, and use :code:`python` as the :opt:`interpreter ` in :file:`ssh.conf`. diff --git a/kittens/ssh/copy.py b/kittens/ssh/copy.py index 364e0437a..98a17b0a5 100644 --- a/kittens/ssh/copy.py +++ b/kittens/ssh/copy.py @@ -26,8 +26,8 @@ Interpret file arguments as glob patterns. --dest -The destination on the remote computer to copy to. Relative paths are resolved -relative to HOME on the remote machine. When this option is not specified, the +The destination on the remote host to copy to. Relative paths are resolved +relative to HOME on the remote host. When this option is not specified, the local file path is used as the remote destination (with the HOME directory getting automatically replaced by the remote HOME). Note that environment variables and ~ are not expanded. diff --git a/kittens/ssh/options/definition.py b/kittens/ssh/options/definition.py index c8fd79579..556e6c8b3 100644 --- a/kittens/ssh/options/definition.py +++ b/kittens/ssh/options/definition.py @@ -8,10 +8,10 @@ from kitty.conf.types import Definition copy_message = '''\ -Copy files and directories from the local computer to the remote one. The -specified files are assumed to be relative to the HOME directory and copied -to the HOME on the server. Directories are copied recursively. If absolute paths -are used, they are copied as is.''' +Copy files and directories from local to remote hosts. The specified files are +assumed to be relative to the HOME directory and copied to the HOME on the +remote. Directories are copied recursively. If absolute paths are used, they are +copied as is.''' definition = Definition( 'kittens.ssh', @@ -29,7 +29,7 @@ hosts can be used. Multiple hostnames can also be specified separated by spaces. The hostname can include an optional username in the form :code:`user@host`. When not specified options apply to all hosts, until the first hostname specification is found. Note that matching of hostname is done against -the name you specify on the command line to connect to the remote computer. +the name you specify on the command line to connect to the remote host. If you wish to include the same basic configuration for many different hosts, you can do so with the :ref:`include ` directive. ''') @@ -41,7 +41,7 @@ an alternate interpreter can be useful. ''') opt('remote_dir', '.local/share/kitty-ssh-kitten', option_type='relative_dir', long_text=''' -The location on the remote computer where the files needed for this kitten +The location on the remote host where the files needed for this kitten are installed. The location is relative to the HOME directory. Absolute paths or paths that resolve to a location outside the HOME are not allowed. ''') @@ -51,7 +51,7 @@ opt('+copy', '', option_type='copy', add_to_default=False, long_text=f''' copy .vimrc .zshrc .config/some-dir -If a file should be copied to some other destination on the remote machine, +If a file should be copied to some other destination on the remote host, use :code:`--dest`:: copy --dest some-other-name some-file @@ -94,7 +94,7 @@ The value of MYVAR2 will be :code:`a//b`. Using :code:`VAR=` will set it to the empty string and using just :code:`VAR` will delete the variable from the child process' environment. The definitions are processed alphabetically. The special value :code:`_kitty_copy_env_var_` -will cause the value of the variable to be copied from the local machine. +will cause the value of the variable to be copied from the local environment. ''') opt('cwd', '', long_text='''