connectors.tunnel_dispatcher

Provides a stdin/stdout based protocol to safely dispatch commands and return their results over any connection that forwards both stdin/stdout, as well as some other needed remote system related utilities.

class tunnel_dispatcher.RemoteOSError

An exception type for remote OSErrors.

class tunnel_dispatcher.Connection

Represents a connection to this dispatcher via an input and output buffer.

def Connection.flush()

def Connection.flush(self) -> None:

Flushes the output buffer.

def Connection.read()

def Connection.read(self, count: int) -> bytes:

Reads exactly the given amount of bytes.

def Connection.write()

def Connection.write(self, data: bytes, count: int) -> None:

Writes exactly the given amount of bytes from data.

def Connection.write_packet()

def Connection.write_packet(self, packet: Any) -> None:

Writes the given packet.

class tunnel_dispatcher.PacketOk

This packet is used by some requests as a generic successful status indicator.

class tunnel_dispatcher.PacketAck

This packet is used to acknowledge a previous PacketCheckAlive packet.

class tunnel_dispatcher.PacketCheckAlive

This packet is used to check whether a connection is alive. The receiver must answer with PacketAck immediately.

def PacketCheckAlive.handle()

def PacketCheckAlive.handle(self, conn: Connection) -> None:

Responds with PacketAck.

class tunnel_dispatcher.PacketExit

This packet is used to signal the server to close the connection and end the dispatcher.

def PacketExit.handle()

def PacketExit.handle(self, conn: Connection) -> None:

Signals the connection to close.

class tunnel_dispatcher.PacketOSError

This packet is sent when an OSError occurs.

class tunnel_dispatcher.PacketInvalidField

This packet is used when an invalid value was given in a previous packet.

class tunnel_dispatcher.PacketProcessCompleted

This packet is used to return the results of a process.

class tunnel_dispatcher.PacketProcessError

This packet is used to indicate an error when running a process or when running the preexec_fn.

class tunnel_dispatcher.PacketProcessRun

This packet is used to run a process.

def PacketProcessRun.handle()

def PacketProcessRun.handle(self, conn: Connection) -> None:

Runs the requested command.

class tunnel_dispatcher.PacketStatResult

This packet is used to return the results of a stat packet.

class tunnel_dispatcher.PacketStat

This packet is used to retrieve information about a file or directory.

def PacketStat.handle()

def PacketStat.handle(self, conn: Connection) -> None:

Stats the requested path.

class tunnel_dispatcher.PacketResolveResult

This packet is used to return the results of a resolve packet.

class tunnel_dispatcher.PacketResolveUser

This packet is used to canonicalize a user name / uid and to ensure it exists. If None is given, it queries the current user.

def PacketResolveUser.handle()

def PacketResolveUser.handle(self, conn: Connection) -> None:

Resolves the requested user.

class tunnel_dispatcher.PacketResolveGroup

This packet is used to canonicalize a group name / gid and to ensure it exists. If None is given, it queries the current group.

def PacketResolveGroup.handle()

def PacketResolveGroup.handle(self, conn: Connection) -> None:

Resolves the requested group.

class tunnel_dispatcher.PacketUpload

This packet is used to upload the given content to the remote and save it as a file. Overwrites existing files. Responds with PacketOk if saving was successful, or PacketInvalidField if any field contained an invalid value.

def PacketUpload.handle()

def PacketUpload.handle(self, conn: Connection) -> None:

Saves the content under the given path.

class tunnel_dispatcher.PacketDownloadResult

This packet is used to return the content of a file.

class tunnel_dispatcher.PacketDownload

This packet is used to download the contents of a given file. Responds with PacketDownloadResult if reading was successful, or PacketInvalidField if any field contained an invalid value.

def PacketDownload.handle()

def PacketDownload.handle(self, conn: Connection) -> None:

Reads the file.

class tunnel_dispatcher.PacketUserEntry

This packet is used to return information about a user.

Attributes

attr name

name: str

The name of the user

attr uid

uid: i64

The numerical user id

attr group

group: str

The name of the primary group

attr gid

gid: i64

The numerical primary group id

attr groups

groups: list[str]

All names of the supplementary groups this user belongs to

attr password_hash

password_hash: Optional[str]

The password hash from shadow

attr gecos

gecos: str

The comment (GECOS) field of the user

attr home

home: str

The home directory of the user

attr shell

shell: str

The default shell of the user

class tunnel_dispatcher.PacketQueryUser

This packet is used to get information about a group via pwd.getpw*.

Attributes

attr user

user: str

User name or decimal uid

attr query_password_hash

query_password_hash: bool

Whether the current password hash from shadow should also be returned

def PacketQueryUser.handle()

def PacketQueryUser.handle(self, conn: Connection) -> None:

Queries the requested user.

class tunnel_dispatcher.PacketGroupEntry

This packet is used to return information about a group.

Attributes

attr name

name: str

The name of the group

attr gid

gid: i64

The numerical group id

attr members

members: list[str]

All the group member's user names

class tunnel_dispatcher.PacketQueryGroup

This packet is used to get information about a group via grp.getgr*.

Attributes

attr group

group: str

Group name or decimal gid

def PacketQueryGroup.handle()

def PacketQueryGroup.handle(self, conn: Connection) -> None:

Queries the requested group.

class tunnel_dispatcher.PacketEnvironVar

This packet is used to return an environment variable.

Attributes

attr value

value: Optional[str]

The value of the environment variable, if it was set.

class tunnel_dispatcher.PacketGetenv

This packet is used to get an environment variable.

Attributes

attr key

key: str

The environment variable to retrieve

def PacketGetenv.handle()

def PacketGetenv.handle(self, conn: Connection) -> None:

Gets the requested environment variable.

Functions

def tunnel_dispatcher.Packet()

def tunnel_dispatcher.Packet(type: str) -> Callable[[Type[Any]], Any]:

Decorator for packet types. Registers the packet and generates read and write methods.

def tunnel_dispatcher.receive_packet()

def tunnel_dispatcher.receive_packet(conn: Connection, request: Any = None
        ) -> Any:

Receives the next packet from the given connection.

Parameters

• conn: The connection

• request: The corresponding request packet, if any.

Returns

• Any: The received packet

Raises

• RemoteOSError: An OSError occurred on the remote host.

• IOError: When an issue on the connection occurs.

• ValueError: When an PacketInvalidField is received as the response and a corresponding request packet was given.