Merge branch 'docs' of https://github.com/page-down/kitty
This commit is contained in:
Kovid Goyal
commit
7c91dc6183
@ -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 <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
|
||||
|
||||
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 <https://man.openbsd.org/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:
|
||||
|
||||
@ -31,18 +31,18 @@ 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::
|
||||
|
||||
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
|
||||
@ -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 <kitten-ssh.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:
|
||||
@ -117,22 +117,22 @@ How it works
|
||||
|
||||
The ssh kitten works by having SSH transmit and execute a POSIX sh (or
|
||||
: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
|
||||
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
|
||||
launching the :opt:`login shell <kitten-ssh.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 <kitten-ssh.login_shell>` with :opt:`shell
|
||||
integration <kitten-ssh.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::
|
||||
|
||||
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
|
||||
<kitten-ssh.interpreter>` in :file:`ssh.conf`.
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -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.
|
||||
'''
|
||||
|
||||
|
||||
|
||||
@ -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',
|
||||
@ -21,26 +21,37 @@ 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
|
||||
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 <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'''
|
||||
{copy_message} For example::
|
||||
|
||||
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
|
||||
@ -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
|
||||
@ -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`
|
||||
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='''
|
||||
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user