KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge branch 'docs' of https://github.com/page-down/kitty

Browse Source
This commit is contained in:
Kovid Goyal 2022-03-22 21:07:05 +05:30
commit 7c91dc6183
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
3 changed files with 71 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/kittens/ssh.rst
View File

@ -1,18 +1,18 @@
Truly convenient SSH Truly convenient SSH
========================================= =========================================
* Automatic :ref:`shell_integration` on remote machines * Automatic :ref:`shell_integration` on remote hosts
* Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote machines * Easily :ref:`clone local shell/editor config <real_world_ssh_kitten_config>` on remote hosts
* Automatic :opt:`re-use of existing connections <kitten-ssh.share_connections>` to avoid connection setup latency * Automatic :opt:`re-use of existing connections <kitten-ssh.share_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 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 files to copy there, making your remote experience just like your
local shell. Additionally, it automatically sets up :ref:`shell_integration` on 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 <https://man.openbsd.org/ssh>`__ The ssh kitten is a thin wrapper around the traditional `ssh <https://man.openbsd.org/ssh>`__
command line program and supports all the same options and arguments and configuration. 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 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 integration enabled. If you like it you can add an alias to it in your shell's
rc files: rc files:
@ -31,18 +31,18 @@ rc files:
alias s=kitty +kitten ssh 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:: If you define a mapping in :file:`kitty.conf` such as::
map f1 new_window_with_cwd map f1 new_window_with_cwd
Then, pressing :kbd:`F1` will open a new window automatically logged 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` 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 file where you can specify environment variables to set on the remote host
and files to copy from your local machine to the remote server. Let's see a and files to copy from the local to the remote host. Let's see a
quick example: quick example:
.. code-block:: conf .. code-block:: conf
@ -51,7 +51,7 @@ quick example:
copy .zshrc .vimrc .vim copy .zshrc .vimrc .vim
# Setup some environment variables # Setup some environment variables
env SOME_VAR=x 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_ env COPIED_VAR=_kitty_copy_env_var_
# Create some per hostname settings # Create some per hostname settings
@ -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 appended to the end of that file. They apply only to the host being SSHed to
by this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are ignored. by this invocation, so any :opt:`hostname <kitten-ssh.hostname>` directives are ignored.
.. note:: .. warning::
Because of limitations of the design of SSH, any typing you do before the Due to the limitations in the design of SSH, any typing you do before the
shell prompt appears may be lost. So ideally dont start typing till you see shell prompt appears may be lost. So ideally don't start typing till you see
the shell prompt 😇. the shell prompt. 😇
.. _real_world_ssh_kitten_config: .. _real_world_ssh_kitten_config:
@ -117,22 +117,22 @@ How it works
The ssh kitten works by having SSH transmit and execute a POSIX sh (or The ssh kitten works by having SSH transmit and execute a POSIX sh (or
:opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the :opt:`optionally <kitten-ssh.interpreter>` Python) bootstrap script on the
remote server using an :opt:`interpreter <kitten-ssh.interpreter>`. This script remote host using an :opt:`interpreter <kitten-ssh.interpreter>`. This script
reads setup data over the tty device, which kitty sends as a base64 encoded 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 <kitten-ssh.copy>` compressed tarball. The script extracts it and places the :opt:`files <kitten-ssh.copy>`
and sets the :opt:`environment variables <kitten-ssh.env>` before finally and sets the :opt:`environment variables <kitten-ssh.env>` before finally
launching the :opt:`login shell <kitten-ssh.login_shell>` with shell launching the :opt:`login shell <kitten-ssh.login_shell>` with :opt:`shell
integration enabled. The data is requested by the kitten over the TTY with a integration <kitten-ssh.shell_integration>` enabled. The data is requested by
random one time password. kitty reads the request and if the password matches the kitten over the TTY with a random one time password. kitty reads the request
a password pre-stored in shared memory on the localhost by the kitten, the and if the password matches a password pre-stored in shared memory on the
transmission is allowed. If your OpenSSH version is >= 8.4 then the data is localhost by the kitten, the transmission is allowed. If your OpenSSH version is
transmitted instantly without any roundtrip delay. >= 8.4 then the data is transmitted instantly without any roundtrip delay.
.. note:: .. 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. 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 is something POSIX sh compliant, and use :code:`python` as the :opt:`interpreter
<kitten-ssh.interpreter>` in :file:`ssh.conf`. <kitten-ssh.interpreter>` in :file:`ssh.conf`.

11
kittens/ssh/copy.py
View File

@ -26,8 +26,8 @@ Interpret file arguments as glob patterns.
--dest --dest
The destination on the remote computer to copy to. Relative paths are resolved The destination on the remote host to copy to. Relative paths are resolved
relative to HOME on the remote machine. When this option is not specified, the 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 local file path is used as the remote destination (with the HOME directory
getting automatically replaced by the remote HOME). Note that environment getting automatically replaced by the remote HOME). Note that environment
variables and ~ are not expanded. variables and ~ are not expanded.
@ -35,9 +35,10 @@ variables and ~ are not expanded.
--exclude --exclude
type=list type=list
A glob pattern. Files whose names would match this pattern after transfer A glob pattern. Files with names matching this pattern are excluded from being
are excluded from being transferred. Useful when adding directories. Can transferred. Useful when adding directories. Can
be specified multiple times, if any of the patterns match the file will be excluded. be specified multiple times, if any of the patterns match the file will be
excluded.
''' '''

76
kittens/ssh/options/definition.py
View File

@ -8,10 +8,10 @@ from kitty.conf.types import Definition
copy_message = '''\ copy_message = '''\
Copy files and directories from the local computer to the remote one. The Copy files and directories from local to remote hosts. The specified files are
specified files are assumed to be relative to the HOME directory and copied assumed to be relative to the HOME directory and copied to the HOME on the
to the HOME on the server. Directories are copied recursively. If absolute paths remote. Directories are copied recursively. If absolute paths are used, they are
are used, they are copied as is.''' copied as is.'''
definition = Definition( definition = Definition(
'kittens.ssh', 'kittens.ssh',
@ -21,26 +21,37 @@ agr = definition.add_group
egr = definition.end_group egr = definition.end_group
opt = definition.add_option opt = definition.add_option
agr('host', 'Host environment') # {{{ agr('bootstrap', 'Host bootstrap configuration') # {{{
opt('hostname', '*', option_type='hostname', opt('hostname', '*', option_type='hostname', long_text='''
long_text=''' The hostname that the following options apply to. A glob pattern to match multiple
The hostname the following options apply to. A glob pattern to match multiple
hosts can be used. Multiple hostnames can also be specified separated by spaces. 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`. The hostname can include an optional username in the form :code:`user@host`.
When not specified options apply to all hosts, until the When not specified options apply to all hosts, until the
first hostname specification is found. Note that matching of hostname is done against 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 If you wish to include the same basic configuration for many
different hosts, you can do so with the :ref:`include <include>` directive. different hosts, you can do so with the :ref:`include <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 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.
''')
opt('+copy', '', option_type='copy', add_to_default=False, long_text=f''' opt('+copy', '', option_type='copy', add_to_default=False, long_text=f'''
{copy_message} For example:: {copy_message} For example::
copy .vimrc .zshrc .config/some-dir 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`:: use :code:`--dest`::
copy --dest some-other-name some-file copy --dest some-other-name some-file
@ -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. Files whose remote name matches the exclude pattern will not be copied.
For more details, see :ref:`ssh_copy_command`. 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=''' opt('+env', '', option_type='env', add_to_default=False, long_text='''
Specify environment variables to set on the remote host. Note that Specify environment variables to set on the remote host. Note that
@ -68,45 +94,25 @@ The value of MYVAR2 will be :code:`a/<path to home directory>/b`. Using
:code:`VAR=` will set it to the empty string and using just :code:`VAR` :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 will delete the variable from the child process' environment. The definitions
are processed alphabetically. The special value :code:`_kitty_copy_env_var_` 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=''' opt('cwd', '', long_text='''
The working directory on the remote host to change to. Env vars in this 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 value are expanded. The default is empty so no changing is done, which
usually means the home directory is used. 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 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 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 to enter the password only once. Under the hood, it uses SSH ControlMasters and
these are automatically cleaned up by kitty when it quits. 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=''' 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 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 etc. The default is to use kitty's native askpass, unless the SSH_ASKPASS