mirror of
https://github.com/kovidgoyal/kitty.git
synced 2024-11-10 13:04:03 +03:00
Docs: Improve ssh kitten documentation
Add more text roles. Put the env example at the end. The alias syntax of fish and bash requires quotation marks. Document `SSH_ASKPASS` in the glossary.
This commit is contained in:
pagedown
parent
9edb772a81
commit
7282f1f684
@ -84,6 +84,12 @@ Variables that influence kitty behavior
|
||||
is possible for the autodiscovery to fail; the default Wayland XKB mappings
|
||||
are used in this case. See :pull:`3943` for details.
|
||||
|
||||
.. envvar:: SSH_ASKPASS
|
||||
|
||||
Specify the program for SSH to ask for passwords. When this is set, :doc:`ssh
|
||||
kitten </kittens/ssh>` will use this environment variable by default. See
|
||||
:opt:`askpass <kitten-ssh.askpass>` for details.
|
||||
|
||||
.. envvar:: KITTY_CLONE_SOURCE_CODE
|
||||
|
||||
Set this to some shell code that will be executed in the cloned window with
|
||||
|
||||
@ -15,28 +15,27 @@ Truly convenient SSH
|
||||
Automatic shell integration, file transfer and reuse of connections
|
||||
|
||||
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 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 host and copies the kitty terminfo database there.
|
||||
setup the environment there to be as comfortable as your local shell. You 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 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.
|
||||
In interactive usage scenarios it is a drop in replacement for ``ssh``. To try it
|
||||
out, simply run:
|
||||
In interactive usage scenarios it is a drop in replacement for :program:`ssh`.
|
||||
To try it out, simply run:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
kitty +kitten ssh some-hostname-to-connect-to
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
alias s=kitty +kitten ssh
|
||||
alias s="kitty +kitten ssh"
|
||||
|
||||
So now you can just type ``s hostname`` to connect.
|
||||
|
||||
@ -44,13 +43,12 @@ 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 host using the ssh kitten, at the same directory.
|
||||
Then, pressing :kbd:`F1` will open a new window automatically logged 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 host
|
||||
and files to copy from the local to the remote host. Let's see a
|
||||
quick example:
|
||||
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 host and files
|
||||
to copy from the local to the remote host. Let's see a quick example:
|
||||
|
||||
.. code-block:: conf
|
||||
|
||||
@ -80,8 +78,9 @@ Additionally, you can pass config options on the command line:
|
||||
|
||||
The :code:`--kitten` argument can be specified multiple times, with directives
|
||||
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.
|
||||
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.
|
||||
|
||||
.. warning::
|
||||
|
||||
@ -98,8 +97,8 @@ A real world example
|
||||
Suppose you often SSH into a production server, and you would like to setup
|
||||
your shell and editor there using your custom settings. However, other people
|
||||
could SSH in as well and you don't want to clobber their settings. Here is how
|
||||
this could be achieved using the ssh kitten with zsh and vim as the shell and
|
||||
editor, respectively:
|
||||
this could be achieved using the ssh kitten with :program:`zsh` and
|
||||
:program:`vim` as the shell and editor, respectively:
|
||||
|
||||
.. code-block:: conf
|
||||
|
||||
@ -125,23 +124,24 @@ 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 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>`
|
||||
and sets the :opt:`environment variables <kitten-ssh.env>` before finally
|
||||
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.
|
||||
localhost by the kitten, the transmission is allowed. If your local
|
||||
`OpenSSH <https://www.openssh.com/>`__ version is >= 8.4 then the data is
|
||||
transmitted instantly without any roundtrip delay.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
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 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`.
|
||||
is something POSIX sh compliant, and use :code:`python` as the
|
||||
:opt:`interpreter <kitten-ssh.interpreter>` in :file:`ssh.conf`.
|
||||
|
||||
.. include:: /generated/conf-kitten-ssh.rst
|
||||
|
||||
|
||||
@ -24,26 +24,26 @@ opt = definition.add_option
|
||||
agr('bootstrap', 'Host bootstrap configuration') # {{{
|
||||
|
||||
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 host.
|
||||
If you wish to include the same basic configuration for many
|
||||
different hosts, you can do so with the :ref:`include <include>` directive.
|
||||
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 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.
|
||||
The interpreter to use on the remote host. Must be either a POSIX complaint
|
||||
shell or a :program:`python` executable. If the default :program:`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.
|
||||
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'''
|
||||
@ -51,8 +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 host,
|
||||
use :code:`--dest`::
|
||||
Use :code:`--dest` to copy a file to some other destination on the remote host::
|
||||
|
||||
copy --dest some-other-name some-file
|
||||
|
||||
@ -79,51 +78,54 @@ 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.
|
||||
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
|
||||
environment variables can refer to each other, so if you use::
|
||||
|
||||
env MYVAR1=a
|
||||
env MYVAR2=$MYVAR1/$HOME/b
|
||||
|
||||
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_`
|
||||
Specify the environment variables to be set on the remote host. Using the
|
||||
name with an equal sign (e.g. :code:`env VAR=`) will set it to the empty string.
|
||||
Specifying only the name (e.g. :code:`env VAR`) will remove the variable from
|
||||
the remote shell environment. The special value :code:`_kitty_copy_env_var_`
|
||||
will cause the value of the variable to be copied from the local environment.
|
||||
The definitions are processed alphabetically. Note that environment variables
|
||||
are expanded recursively, for example::
|
||||
|
||||
env VAR1=a
|
||||
env VAR2=${HOME}/${VAR1}/b
|
||||
|
||||
The value of :code:`VAR2` will be :code:`<path to home directory>/a/b`.
|
||||
''')
|
||||
|
||||
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.
|
||||
The working directory on the remote host to change to. Environment variables in
|
||||
this value are expanded. The default is empty so no changing is done, which
|
||||
usually means the HOME directory is used.
|
||||
''')
|
||||
|
||||
opt('color_scheme', '', long_text='''
|
||||
Specify a color scheme to use when connecting to the remote host. If the
|
||||
color_scheme ends with :code:`.conf` it is assumed to be the name of a config
|
||||
file to load from the kitty config directory, otherwise it is assumed to be the
|
||||
name of a color theme to load via the themes kitten. Note that only colors
|
||||
applying to the text/background are changed, other config settings in the .conf
|
||||
files/themes are ignored.
|
||||
Specify a color scheme to use when connecting to the remote host. If this option
|
||||
ends with :code:`.conf`, it is assumed to be the name of a config file to load
|
||||
from the kitty config directory, otherwise it is assumed to be the name of a
|
||||
color theme to load via the :doc:`themes kitten </kittens/themes>`. Note that
|
||||
only colors applying to the text/background are changed, other config settings
|
||||
in the .conf files/themes are ignored.
|
||||
''')
|
||||
|
||||
opt('remote_kitty', 'if-needed', choices=('if-needed', 'no', 'yes'), long_text='''
|
||||
Make kitty available on the remote server. Useful to run kittens such as the
|
||||
icat kitten to display images or the transfer file kitten to transfer files.
|
||||
Only works if the remote server has an architecture for which pre-compiled
|
||||
kitty binaries are available. Note that kitty is not actually copied to the
|
||||
remote server, instead a small bootstrap script is copied which will download
|
||||
and run kitty when kitty is first executed on the remote server. A value of
|
||||
:code:`if-needed` means kitty is installed only if not already present in the
|
||||
system-wide PATH. A value of :code:`yes` means that kitty is installed even if
|
||||
already present, and the installed kitty takes precedence. Finally, :code:`no`
|
||||
means no kitty is installed on the remote machine. The installed kitty
|
||||
can be updated by running: :code:`kitty +update-kitty` on the remote machine.
|
||||
Make :program:`kitty` available on the remote host. Useful to run kittens such
|
||||
as the :doc:`icat kitten </kittens/icat>` to display images or the
|
||||
:doc:`transfer file kitten </kittens/transfer>` to transfer files. Only works if
|
||||
the remote host has an architecture for which :link:`pre-compiled kitty binaries
|
||||
<https://github.com/kovidgoyal/kitty/releases>` are available. Note that kitty
|
||||
is not actually copied to the remote host, instead a small bootstrap script is
|
||||
copied which will download and run kitty when kitty is first executed on the
|
||||
remote host. A value of :code:`if-needed` means kitty is installed only if not
|
||||
already present in the system-wide PATH. A value of :code:`yes` means that kitty
|
||||
is installed even if already present, and the installed kitty takes precedence.
|
||||
Finally, :code:`no` means no kitty is installed on the remote host. The
|
||||
installed kitty can be updated by running: :code:`kitty +update-kitty` on the
|
||||
remote host.
|
||||
''')
|
||||
egr() # }}}
|
||||
|
||||
@ -131,20 +133,21 @@ 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.
|
||||
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('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
|
||||
environment variable is set. Set it to :code:`ssh` to not interfere with the
|
||||
normal ssh askpass mechanism at all, which typically means that ssh will prompt
|
||||
at the terminal. Set it to :code:`native` to always use kitty's native,
|
||||
built-in askpass implementation. Note that not using the kitty askpass implementation
|
||||
means that SSH might need to use the terminal before the connection is established
|
||||
so the kitten cannot use the terminal to send data without an extra roundtrip,
|
||||
adding to initial connection latency.
|
||||
etc. The default is to use kitty's native :program:`askpass`, unless the
|
||||
:envvar:`SSH_ASKPASS` environment variable is set. Set this option to
|
||||
:code:`ssh` to not interfere with the normal ssh askpass mechanism at all, which
|
||||
typically means that ssh will prompt at the terminal. Set it to :code:`native`
|
||||
to always use kitty's native, built-in askpass implementation. Note that not
|
||||
using the kitty askpass implementation means that SSH might need to use the
|
||||
terminal before the connection is established, so the kitten cannot use the
|
||||
terminal to send data without an extra roundtrip, adding to initial connection
|
||||
latency.
|
||||
''')
|
||||
egr() # }}}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user