3~hddlmZddlmZddlmZddlZddlmZddlm Z ddl m Z ddl m Z dd lmZmZdd lmZdd lmZd d lmZd dlmZd dlmZd dlmZmZedZdZGdde Z y))contextmanager)StringIO)EventN) decorator)Context)ThreadException)AgentRequestHandler) SSHClient AutoAddPolicy) SSHConfig) ProxyCommand)Config) InvalidV1Env)Transfer) TunnelManagerTunnelc:|j||g|i|SN)open)methodselfargskwargss Z/var/www/peopleoo.sandbox-dev.co.uk/venv/lib/python3.12/site-packages/fabric/connection.pyopensrs IIK $ ( ( ((c$|jdd}|j}|r |dr|dnd}|jddkDr|}d}n5|jdd}|jdxsd}|r |dr|dnd}| t|}|||dS)N@rr:)userhostport)rsplitpopcountint) host_string user_hostporthostportr!r"r# host_ports rderive_shorthandr,s&&sA.M  "H,q1A= tD ~~cQOOC+ }}Q'4(Yq\y|t 4y$ 55rceZdZdZdZdZdZdZdZdZ dZ dZ dZ dZ dZdZdZedZ dfd ZdZdZdZdZd Zd Zd Zd Zed ZdZdZdZ dZ!dZ"e#dZ$dZ%e#dZ&e#dZ'e#dZ(fdZ)e#dZ*dZ+dZ,e-e# ddZ.e-e# d dZ/xZ0S)! Connectionaq A connection to an SSH daemon, with methods for commands and file transfer. **Basics** This class inherits from Invoke's `~invoke.context.Context`, as it is a context within which commands, tasks etc can operate. It also encapsulates a Paramiko `~paramiko.client.SSHClient` instance, performing useful high level operations with that `~paramiko.client.SSHClient` and `~paramiko.channel.Channel` instances generated from it. .. _connect_kwargs: .. note:: Many SSH specific options -- such as specifying private keys and passphrases, timeouts, disabling SSH agents, etc -- are handled directly by Paramiko and should be specified via the :ref:`connect_kwargs argument ` of the constructor. **Lifecycle** `.Connection` has a basic "`create <__init__>`, `connect/open `, `do work `, `disconnect/close `" lifecycle: - `Instantiation <__init__>` imprints the object with its connection parameters (but does **not** actually initiate the network connection). - An alternate constructor exists for users :ref:`upgrading piecemeal from Fabric 1 `: `from_v1` - Methods like `run`, `get` etc automatically trigger a call to `open` if the connection is not active; users may of course call `open` manually if desired. - It's best to explicitly close your connections when done using them. This can be accomplished by manually calling `close`, or by using the object as a contextmanager:: with Connection('host') as c: c.run('command') c.put('file') .. warning:: While Fabric (and Paramiko) attempt to register connections for automatic garbage collection, it's not currently safe to rely on that feature, as it can lead to end-of-process hangs and similar behavior. .. note:: This class rebinds `invoke.context.Context.run` to `.local` so both remote and local command execution can coexist. **Configuration** Most `.Connection` parameters honor :doc:`Invoke-style configuration ` as well as any applicable :ref:`SSH config file directives `. For example, to end up with a connection to ``admin@myhost``, one could: - Use any built-in config mechanism, such as ``/etc/fabric.yml``, ``~/.fabric.json``, collection-driven configuration, env vars, etc, stating ``user: admin`` (or ``{"user": "admin"}``, depending on config format.) Then ``Connection('myhost')`` would implicitly have a ``user`` of ``admin``. - Use an SSH config file containing ``User admin`` within any applicable ``Host`` header (``Host myhost``, ``Host *``, etc.) Again, ``Connection('myhost')`` will default to an ``admin`` user. - Leverage host-parameter shorthand (described in `.Config.__init__`), i.e. ``Connection('admin@myhost')``. - Give the parameter directly: ``Connection('myhost', user='admin')``. The same applies to agent forwarding, gateways, and so forth. .. versionadded:: 2.0 Nc |js td|jdi}|jd|jt|j}|jd|j|ds%|jdt |j |j|jd|jd|vrtj||d<|di|S) a Alternate constructor which uses Fabric 1's ``env`` dict for settings. All keyword arguments besides ``env`` are passed unmolested into the primary constructor. .. warning:: Because your own config overrides will win over data from ``env``, make sure you only set values you *intend* to change from your v1 environment! For details on exactly which ``env`` vars are imported and what they become in the new API, please see :ref:`v1-env-var-imports`. :param env: An explicit Fabric 1 ``env`` dict (technically, any ``fabric.utils._AttributeDict`` instance should work) to pull configuration from. .. versionadded:: 2.4 zSupplied v1 env has an empty `host_string` value! Please make sure you're calling Connection.from_v1 within a connected Fabric 1 session.connect_kwargsr"r!r# key_filenameconfig) r(r setdefaultr,r!r'r#r1rfrom_v1)clsenvrr0 shorthands rr5zConnection.from_v1s8\   **+;R@&#//2$S__5 &#((+   fc#((m 4    '  % %nc6F6F G 6 !%~~c2F8 }V}rc Ht||| t}n&t|ts|j t}|j ||j |} | d}d} | d!|t| jd| d}| d!|t| jd| d}|jjj||_ ||_ ||_d |jvr|jd |_|xs0|jjd|jj |_|xs9t#|jjd|jj$|_||n|j'|_|;|jj*}d |jvrd d d } | |jd }||_|:|jjd|jj,j.}| t#|}||_|j3||_t7} | j9t;| |_d|_| |jj@} | |_ y)a Set up a new object representing a server connection. :param str host: the hostname (or IP address) of this connection. May include shorthand for the ``user`` and/or ``port`` parameters, of the form ``user@host``, ``host:port``, or ``user@host:port``. .. note:: Due to ambiguity, IPv6 host addresses are incompatible with the ``host:port`` shorthand (though ``user@host`` will still work OK). In other words, the presence of >1 ``:`` character will prevent any attempt to derive a shorthand port number; use the explicit ``port`` parameter instead. .. note:: If ``host`` matches a ``Host`` clause in loaded SSH config data, and that ``Host`` clause contains a ``Hostname`` directive, the resulting `.Connection` object will behave as if ``host`` is equal to that ``Hostname`` value. In all cases, the original value of ``host`` is preserved as the ``original_host`` attribute. Thus, given SSH config like so:: Host myalias Hostname realhostname a call like ``Connection(host='myalias')`` will result in an object whose ``host`` attribute is ``realhostname``, and whose ``original_host`` attribute is ``myalias``. :param str user: the login user for the remote connection. Defaults to ``config.user``. :param int port: the remote port. Defaults to ``config.port``. :param config: configuration settings to use when executing methods on this `.Connection` (e.g. default SSH port and so forth). Should be a `.Config` or an `invoke.config.Config` (which will be turned into a `.Config`). Default is an anonymous `.Config` object. :param gateway: An object to use as a proxy or gateway for this connection. This parameter accepts one of the following: - another `.Connection` (for a ``ProxyJump`` style gateway); - a shell command string (for a ``ProxyCommand`` style style gateway). Default: ``None``, meaning no gatewaying will occur (unless otherwise configured; if one wants to override a configured gateway at runtime, specify ``gateway=False``.) .. seealso:: :ref:`ssh-gateways` :param bool forward_agent: Whether to enable SSH agent forwarding. Default: ``config.forward_agent``. :param int connect_timeout: Connection timeout, in seconds. Default: ``config.timeouts.connect``. :param dict connect_kwargs: .. _connect_kwargs-arg: Keyword arguments handed verbatim to `SSHClient.connect ` (when `.open` is called). `.Connection` tries not to grow additional settings/kwargs of its own unless it is adding value of some kind; thus, ``connect_kwargs`` is currently the right place to hand in paramiko connection parameters such as ``pkey`` or ``key_filename``. For example:: c = Connection( host="hostname", user="admin", connect_kwargs={ "key_filename": "/home/myuser/.ssh/private.key", }, ) Default: ``config.connect_kwargs``. :param bool inline_ssh_env: Whether to send environment variables "inline" as prefixes in front of command strings (``export VARNAME=value && mycommand here``; this is the default behavior), or submit them through the SSH protocol itself. In Fabric 2.x this defaulted to ``False`` (try using the protocol behavior), but in 3.x it changed to ``True`` due to the simple fact that most remote servers are deployed with a restricted ``AcceptEnv`` setting, making use of the protocol approach non-viable. The actual default value is the value of the ``inline_ssh_env`` :ref:`configuration value ` (which, as above, currently defaults to ``True``). .. warning:: This functionality does **not** currently perform any shell escaping on your behalf! Be careful when using nontrivial values, and note that you can put in your own quoting, backslashing etc if desired. Consider using a different approach (such as actual remote shell scripts) if you run into too many issues here. .. note:: When serializing into prefixed ``FOO=bar`` format, we apply the builtin `sorted` function to the env dictionary's keys, to remove what would otherwise be ambiguous/arbitrary ordering. .. note:: This setting has no bearing on *local* shell commands; it only affects remote commands, and thus, methods like `.run` and `.sudo`. :raises ValueError: if user or port values are given via both ``host`` shorthand *and* their own arguments. (We `refuse the temptation to guess`_). .. _refuse the temptation to guess: http://zen-of-python.info/ in-the-face-of-ambiguity-refuse-the-temptation-to-guess.html#12 .. versionchanged:: 2.3 Added the ``inline_ssh_env`` parameter. .. versionchanged:: 3.0 ``inline_ssh_env`` still defaults to the config value, but said config value has now changed and defaults to ``True``, not ``False``. r2N)into)_configr"zBYou supplied the {} via both shorthand and kwarg! Please pick one.r!r#hostname forwardagentTF)yesnoconnecttimeout)!super__init__r isinstanceclone_setr, ValueErrorformatr2base_ssh_configlookup ssh_config original_hostr"getr!r'r# get_gatewaygateway forward_agenttimeoutsconnectconnect_timeoutresolve_connect_kwargsr0r set_missing_host_key_policyr client transportinline_ssh_env)rr"r!r#r2rOrPrSr0rXr8errmap_rV __class__s rrCzConnection.__init__stL ' >XFFF+\\v\.F & !))$/  R V  ( F!344V$D V  ( F!344V$D ++55<">O  &!/2O.#99.I**=?;   !![[77N-rc8|xsi}|jj}|jdg}|jdg}|jjdg}|xs|}g}|||fD]&} t | t r| g} |j | (|r||d<|S)Nr1 identityfile)r2r0rMrKrDstrextend) rr0constructor_kwargs config_kwargsconstructor_keys config_keysssh_config_keys final_kwargs final_keysvalues rrTz!Connection.resolve_connect_kwargss ,1r 22 -11."E#''; //--nbA*:]  !#3_E %E%%   e $ % +5L (rcd|jvrt|jdjd}d}|D]^}|j|d|jk(ryt |j j}|||d<t|fi|}|}`|Sd|jvr|jdS|j jS)N proxyjump,r"r:rO proxycommand) rKreversedsplitr,r"dictr2rEr.rO)rhopsprev_gwhoprcxns rrNzConnection.get_gateways $// )DOOK8>>sCDDG  ((-f5BT[[%6%6%89&(/F9% // N t .??>2 2{{"""rcd|jfg}|j|jjk7r|jd|jf|j|jjk7r|jd|jf|j r1d}t |j trd}|jd|fdjdjd |DS) Nr"r!r#rirkgwz c3:K|]}dj|yw)z{}={}N)rH).0xs r z&Connection.__repr__..(s6A^W^^Q'6s) r"r!r2appendr#rOrDr^rHjoin)rbitsvals r__repr__zConnection.__repr__s#$ 99 (( ( KK+ , 99 (( ( KK+ , <<C$,,,$ KKs $ '' HH66 6  rcH|j|j|jfSr)r"r!r#rs r _identityzConnection._identity+s 499dii00rcft|tsy|j|jk(S)NF)rDr.rrothers r__eq__zConnection.__eq__1s(%,~~5??#444rcD|j|jkSr)rrs r__lt__zConnection.__lt__6s~~%//"333rc4t|jSr)hashrrs r__hash__zConnection.__hash__9sDNN$%%rct|Sr)r,)rr(s rr,zConnection.derive_shorthand>s ,,rcJ|jr|jjSdS)za Whether or not this connection is actually open. .. versionadded:: 2.0 F)rWactivers r is_connectedzConnection.is_connectedDs)-t~~$$AEArc0|jryd}djD]*}||jvst|j |d|jvr&|j t|j dt |j|j|j|j}|jr|j|d<|j r|j |d<d|vr|ds|d=|jj}|EdD]}|j|d||j|j |j |d <|j"j$d i|}|j"j'|_|S) a Initiate an SSH connection to the host/port this object is bound to. This may include activating the configured gateway connection, if one is set. Also saves a handle to the now-set Transport object for easier access. Various connect-time settings (and/or their corresponding :ref:`SSH config options `) are utilized here in the call to `SSHClient.connect `. (For details, see :doc:`the configuration docs `.) :returns: The result of the internal call to `.SSHClient.connect`, if performing an initial connection; ``None`` otherwise. .. versionadded:: 2.0 .. versionchanged:: 3.1 Now returns the inner Paramiko connect call's return value instead of always returning the implicit ``None``. NzeRefusing to be ambiguous: connect() kwarg '{}' was given both via regular arg and via connect_kwargs!zD hostname port username timeout)usernamer=r#sockr1) allow_agentr1 look_for_keys passphrasepasswordpkeyr)rK fabric_configr auth_strategyr3)rrmr0rGrHrSrnr!r"r#rO open_gatewayauthenticationstrategy_classr%rKr2rVrR get_transportrW)rrYkeyrauth_strategy_classresults rrzConnection.openMs0    u  EG  2C d))) C11  2 ,, ,$$0SZZ 23 3   YYYY   <<!..0F6N    $ 4 4F9  V #F>,B~&"11@@  * & 3% &':??"kk'F? # %$$.v.224 rct|jtrqt}d}|j t |j |j|jt|j|jdS|jj|jjjd|jt|jfdS)a$ Obtain a socket-like object from `gateway`. :returns: A ``direct-tcpip`` `paramiko.channel.Channel`, if `gateway` was a `.Connection`; or a `~paramiko.proxy.ProxyCommand`, if `gateway` was a string. .. versionadded:: 2.0 zHost {} ProxyCommand {}rkz direct-tcpip)r)kind dest_addrsrc_addr)rDrOr^r parserrHr"r rJrrW open_channelr'r#)rssh_confdummys rrzConnection.open_gateways dllC (!{H2E NN8ELLDLL$IJ K :> JK K ||%%22yy#dii.1 3  rc|j!|jjd|_|jrO|jj|jr(|j |j jyyyy)ag Terminate the network connection to the remote end, if open. If any SFTP sessions are open, they will also be closed. If no connection or SFTP session is open, this method does nothing. .. versionadded:: 2.0 .. versionchanged:: 3.0 Now closes SFTP sessions too (2.x required manually doing so). N)_sftpcloserrVrP_agent_handlerrs rrzConnection.closesr :: ! JJ   DJ    KK   !!d&9&9&E##))+'F! rc|Srr3rs r __enter__zConnection.__enter__s rc$|jyr)r)rexcs r__exit__zConnection.__exit__s  rcr|jj}|jrt||_|Sr)rW open_sessionrPr r)rchannels rcreate_sessionzConnection.create_sessions/..--/   "5g">D rcd|jjj||jS)N)context inline_env)r2runnersremoterXrs r_remote_runnerzConnection._remote_runners/{{""))T%8%8*  rc F|j|j|fi|S)a Execute a shell command on the remote end of this connection. This method wraps an SSH-capable implementation of `invoke.runners.Runner.run`; see its documentation for details. .. warning:: There are a few spots where Fabric departs from Invoke's default settings/behaviors; they are documented under `.Config.global_defaults`. .. versionadded:: 2.0 )_runrrcommandrs rrunzConnection.runs%tyy,,.B6BBrc F|j|j|fi|S)a Execute a shell command, via ``sudo``, on the remote end. This method is identical to `invoke.context.Context.sudo` in every way, except in that -- like `run` -- it honors per-host/per-connection configuration overrides in addition to the generic/global ones. Thus, for example, per-host sudo passwords may be configured. .. versionadded:: 2.0 )_sudorrs rsudozConnection.sudos%tzz$--/CFCCrc |jjj|}d}i}|jjdj D];\}}||vr-|j ||jj |||<7|||<=|jd|r3d}t|jt|j|j d ddi|S) a Run an interactive login shell on the remote end, as with ``ssh``. This method is intended strictly for use cases where you can't know what remote shell to invoke, or are connecting to a non-POSIX-server environment such as a network appliance or other custom SSH server. Nearly every other use case, including interactively-focused ones, will be better served by using `run` plus an explicit remote shell command (eg ``bash``). `shell` has the following differences in behavior from `run`: - It still returns a `~invoke.runners.Result` instance, but the object will have a less useful set of attributes than with `run` or `local`: - ``command`` will be ``None``, as there is no such input argument. - ``stdout`` will contain a full record of the session, including all interactive input, as that is echoed back to the user. This can be useful for logging but is much less so for doing programmatic things after the method returns. - ``stderr`` will always be empty (same as `run` when ``pty==True``). - ``pty`` will always be True (because one was automatically used). - ``exited`` and similar attributes will only reflect the overall session, which may vary by shell or appliance but often has no useful relationship with the internally executed commands' exit codes. - This method behaves as if ``warn`` is set to ``True``: even if the remote shell exits uncleanly, no exception will be raised. - A pty is always allocated remotely, as with ``pty=True`` under `run`. - The ``inline_env`` setting is ignored, as there is no default shell command to add the parameters to (and no guarantee the remote end even is a shell!) It supports **only** the following kwargs, which behave identically to their counterparts in `run` unless otherwise stated: - ``encoding`` - ``env`` - ``in_stream`` (useful in niche cases, but make sure regular `run` with this argument isn't more suitable!) - ``replace_env`` - ``watchers`` (note that due to pty echoing your stdin back to stdout, a watcher will see your input as well as program stdout!) Those keyword arguments also honor the ``run.*`` configuration tree, as in `run`/`sudo`. :returns: `~invoke.runners.Result` :raises: `~invoke.exceptions.ThreadException` (if the background I/O threads encountered exceptions other than `~invoke.exceptions.WatcherError`). .. versionadded:: 2.7 )r)encodingr7 in_stream replace_envwatchersrT)ptyz.shell() got unexpected keyword arguments: {!r}rNr3) r2r remote_shellglobal_defaultsitemsr%rupdate TypeErrorrHlistkeys)rrrunnerallowed new_kwargsrrgrYs rshellzConnection.shell sx$$11$1?N ++557>DDF (JCg~#)**S$++//#2F"G 3"' 3  ( d# BCCJJtFKKM':;< <vzz5$5*55rc"t||i|S)z Execute a shell command on the local system. This method is effectively a wrapper of `invoke.run`; see its docs for details and call signature. .. versionadded:: 2.0 )rBr)rrrr[s rlocalzConnection.local[sw{D+F++rcp|j|jj|_|jS)ao Return a `~paramiko.sftp_client.SFTPClient` object. If called more than one time, memoizes the first result; thus, any given `.Connection` instance will only ever have a single SFTP client, and state (such as that managed by `~paramiko.sftp_client.SFTPClient.chdir`) will be preserved. .. versionadded:: 2.0 )rrV open_sftprs rsftpzConnection.sftphs, :: ..0DJzzrc8t|j|i|S)z Get a remote file to the local filesystem or file-like object. Simply a wrapper for `.Transfer.get`. Please see its documentation for all details. .. versionadded:: 2.0 )rrMrrrs rrMzConnection.getx "x~!!42622rc8t|j|i|S)z Put a local file (or file-like object) to the remote filesystem. Simply a wrapper for `.Transfer.put`. Please see its documentation for all details. .. versionadded:: 2.0 )rputrs rrzConnection.putrrc#K|s|}t}t|||||j|}|j d|j |j |j }|*|jtur |jt|gy#|j |j |j }|*|jtur |jt|gwxYww)a Open a tunnel connecting ``local_port`` to the server's environment. For example, say you want to connect to a remote PostgreSQL database which is locked down and only accessible via the system it's running on. You have SSH access to this server, so you can temporarily make port 5432 on your local system act like port 5432 on the server:: import psycopg2 from fabric import Connection with Connection('my-db-server').forward_local(5432): db = psycopg2.connect( host='localhost', port=5432, database='mydb' ) # Do things with 'db' here This method is analogous to using the ``-L`` option of OpenSSH's ``ssh`` program. :param int local_port: The local port number on which to listen. :param int remote_port: The remote port number. Defaults to the same value as ``local_port``. :param str local_host: The local hostname/interface on which to listen. Default: ``localhost``. :param str remote_host: The remote hostname serving the forwarded remote port. Default: ``localhost`` (i.e., the host this `.Connection` is connected to.) :returns: Nothing; this method is only useful as a context manager affecting local operating system state. .. versionadded:: 2.0 ) local_port local_host remote_port remote_hostrWfinishedN) rrrWstartsetr{ exceptiontyperrg)rrrrrrmanagerwrappers r forward_localzConnection.forward_localsb$K 7!!##nn    5  LLN LLN'')G"<.callback<sF==?D LL*j1 2G$IF LLN NN6 "r)addressr#handlerN)rr#)rWrequest_port_forwardrrr{cancel_port_forward)rrrrrrrrs ` ` @rforward_remotezConnection.forward_remotesj$J  #  NN / /#+x 0  " ##%   NN . .#+ / " ##%   NN . .#+ / sC"BACACC)NNNNNNNN)N localhostr)Nz 127.0.0.1r)1__name__ __module__ __qualname____doc__r"rLr!r#rKrOrPrSr0rVrWrr classmethodr5rCrTrNr~rrrrr,propertyrrrrrrrrrrrrrrrMrrrr __classcell__)r[s@rr.r.1sH` DM D DJGMON FI EN77F D-L:#< 21 5 4& - BBN`& P,*     C C   D  D M6 M6^ ,     3 3  Z5 Z5B  e err.)! contextlibrior threadingrrrinvokerinvoke.exceptionsrparamiko.agentr paramiko.clientr r paramiko.configr paramiko.proxyr r2r exceptionsrtransferrrrrrr,r.r3rrr sY% -.4%'$* ) ) 6.jjr