ServerInterface¶

class jetstream.serverinterface.ServerInterface(api_interface, sync_interface, logging_interface)¶

Method Summary¶

`addWranglerAsync`	Gives a user or a group wrangler permissions.
`auth`	Authenticates a user.
`authAsync`	Authenticates a user.
`authToken`	Authenticates using a shared token.
`createAPIToken`	Creates an API token to allow restricted login access.
`deleteAPIToken`	Deletes the specified api token.
`deleteSandboxMapping`	Deletes the sandbox mappings for a user.
`deleteWrangler`	Delete wrangler permissions from a user or a group.
`duAsync`	Submits a request to retrieve the total size, in bytes, for all files in the specified remote path, as visible to the connected server.
`echo`	Sends the (optionally) given text to the server, and returns it from the server.
`garbageCollect`	Initiates an immediate garbage collection on the connected server.
`getAPIToken`	Returns a structure describing an API token.
`getAPITokens`	Returns information for all known api tokens.
`getEventLog`	Returns the JetStream event log.
`getIdleReceiverPort`	Returns receiver port to be used for initiating transfer.
`getIdleReceiverPortAsync`	Returns receiver port asynchronously to be used for initiating transfer.
`getRequestResult`	Returns the result for an asynchronous request.
`getRequestStatus`	Returns the status for an asynchronous request.
`getSandboxMappings`	Gets the sandbox mappings for all users.
`getServerInfo`	Returns information about the connected server, including its name and API version.
`getThirdPartyLicenses`	Returns the licenses for third-party software components used by JetStream.
`getTransportRoutes`	Lists this server's transport routing table.
`getWranglers`	Gets the list of wrangler user and groups.
`listSyncFolders`	Lists the sync folder registrations the connected server holds.
`lsAsync`	Submits a request to retrieve a list of remote files, as visible to the connected server.
`lsListAsync`	Submits a request to retrieve a list of remote files, as visible to the connected server.
`lsRootsAsync`	Submits a request to retrieve a list of the root folders, as visible to the connected server.
`mkFileAsync`	Submits a request to create a new file on the connected server.
`mkdirAsync`	Submits a request to create a new directory on the connected server, creating all parent directories as needed.
`mvAsync`	Submits a request to move or rename a path on the connected server.
`recvDiscoverPacketAsync`	Creates a request to wait for an incoming receiver discovery packet.
`registerSyncFolder`	Registers a pairing between a local folder and a folder on a remote server.
`resetSyncFolder`	Discards every sync folder registration on the connected server, for all users.
`rmAsync`	Submits a request to remove a path on the connected server.
`sendDiscoverPacketAsync`	Sends a discovery packet to a waiting server.
`setExternalAddress`	Sets the external address for the server.
`setLicenseKeyAsync`	Submits a request to set the license key for the server.
`setSandboxMapping`	Sets the sandbox mappings for a user.
`setTransportRoutes`	Sets this server's transport routing table.
`setWebShareBranding`	Reload the branding document for the browser download pages.
`sleep`	Sleep for specified number of milliseconds.
`superuser`	Gives a user permission to access and modify all data, and access admin functions.
`terminate`	Terminate the server.
`unregisterSyncFolder`	Removes a sync folder pairing.
`updateAPIToken`	Updates the specified API token.
`updateBandwidthLimits`	Sets limits on incoming and outgoing bandwidth utilization.
`updateGarbageCollectSettings`	Updates garbage collection.
`updateSchedulerParams`	Adjusts the urgency scheduler's ceiling and admission while the server is running.
`updateSyncFolder`	Updates an existing sync folder pairing.
`validateSyncFolder`	Checks whether a sync folder pairing is registered.
`wrangler`	Gives a user permission to access and modify all data.

Method Documentation¶

ServerInterface.addWranglerAsync(name, isGroup=None)¶

Gives a user or a group wrangler permissions.

Wranglers can only be modified by a superuser.

Wranglers have the ability to list and modify objects from any user. See (see wrangler()).

Parameters:

name (string) – The user name or group name to be added as a wrangler.
isGroup (bool) – The name represents a group instead of a user.

Returns:

None

Raises:

CommandError – If the user is not granted superuser privileges, or the user or group
does not exist. –

Added in version 2.5.0.

ServerInterface.auth(userName, password)¶

Authenticates a user.

Helper method for authAsync() to make the call synchronous.

Parameters:

userName (string) – Name of the user on the JetStream server.
password (string) – Password for the user above. Pass in getpass.getpass() if you wish to input the password interactively.

Returns:

None

Raises:

CommandError – On auth failure

ServerInterface.authAsync(userName=None, password=None, token=None, tokenSession=None)¶

Authenticates a user.

If the JetStream server is running as root or daemon, you must call either auth() or authAsync() after calling connect(), before any other method is called (except getServerInfo())

Parameters:

userName (string) – Name of the user on the JetStream server. Must be None if token is set.
password (string) – Password for the user or token.
token (string) – Shared token. Must be None if userName is set.
tokenSession (string) – Shared token session. If token is set, this parameter specifies the optional session. Sharing a session between two token authed connections allows them to share data such as transfers. If tokenSession is not specified, one will be generated automatically. The current token session is returned by getServerInfo().

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return None on success, or raise a CommandError.

Return type:

dict

Tip

Use getpass.getpass() to prompt for the password parameter interactively.

ServerInterface.authToken(token, password=None, tokenSession=None)¶

Authenticates using a shared token.

Helper method for authAsync() to make the call synchronous.

Parameters:

token (string) – Shared token as generated by createSharedToken()
password (string) – Password for the token above. Pass in getpass.getpass() if you wish to input the password interactively.
tokenSession (string) – Shared token session. If token is set, this parameter specifies the optional session. Sharing a session between two token authed connections allows them to share data such as transfers. If tokenSession is not specified, one will be generated automatically. The current token session is returned by getServerInfo().

Returns:

None

Raises:

CommandError – On auth failure

ServerInterface.createAPIToken(path=None, password=None, timeLimitSeconds=None, description=None, permissions=None)¶

Creates an API token to allow restricted login access.

Createa an API token with optional password that can be used to log into the server. When logged in, the token will impersonate the user that created it, and all file operations will occur as that user. Permissions and sandbox path access, however, can be restricted so that the token user does not have all the same rights as the original user.

Common use cases include creating a token with access only to a specific directory (shared folder), or creating a token for use in scripting so that the user’s credentials remain private. Tokens are time limited, and can be revoked at any time, so can be used as a type of simple user management. Keep in mind, however, that file permissions are still restricted to the original user.

The returned structure provides a ‘token’ string which may be be used by clients to log on.

Parameters:

path – (optional) If provided, the token user will only have access to the given path. If not provided, then the token user will have access to all paths/drives/sandboxes as the user.
password (str) – (optional) A password required to auth this token.
timeLimitSeconds – (optional) Number of seconds from now before this token expires.
description – (optional) A description of what this token represents.
permissions – (optional) Permissions of the token. See constants defined in jetstream.constants.Permissions.

Returns:

Token Structure

Return type:

dict

See also

API Tokens

Added in version 2.4.0.

ServerInterface.getEventLog(eventName=None, before=None, after=None, limit=None)¶

Returns the JetStream event log.

The log is retrieved chronologically, ordered oldest event to newest. Optional parameters may be provided to filter which events are retrieved.

Parameters:

eventName (str) – (optional) Filters the results to include only this event type. If None, retrieve all events.
before (int) – (optional) Filters the results to include only events before this time. If None, retrieve all entries to the end of the log.
after (int) – (optional) Filters the results to include only events after this time. If None, retrieve all entries from the start of the log.
limit (int) – (optional) The maximum number of log entries to retrieve. If None, retrieve all entries.

Returns:

Dictionary with an eventLog key containing a list of event log structures.

Return type:

dict

Example

>>> api.server.getEventLog()
{'eventLog': [{'_event': 'serverStarted', '_timestamp': 1485547699055816},
              {'_event': 'destinationCreated',
               '_timestamp': 1485547708422759,
               'destinationId': '127.0.0.1:8886'}
             ]
}

ServerInterface.getIdleReceiverPort()¶

Returns receiver port to be used for initiating transfer.

Tip

This method does not require authentication.

Returns:: :ref:``
Return type:: dict

ServerInterface.getIdleReceiverPortAsync()¶

Returns receiver port asynchronously to be used for initiating transfer.

Tip

This method does not require authentication.

Returns:: :ref:``
Return type:: dict

ServerInterface.getRequestResult(requestId)¶

Returns the result for an asynchronous request.

API methods whose name ends with Async represent asynchronous requests. These methods are sent a request which must be processed by the destination server, and return a requestId.

getRequestResult() returns the result from an asynchronous request, where the request is identified with its requestId.

If the request is not yet complete, this blocks until the result is available.

If a request fails, getRequestResult() will yield None. Use getRequestStatus() to determine the cause of the failure.

Note

Allowing the results from asynchronous requests to be retrieved at an arbitrary time means that the result must be cached on the server. To avoid resource exhaustion, requests are set to expire after a period a time. Once expired, a request is no longer available.

Parameters:

requestId (int, dict) – A request ID or Request Structure.

Returns:

A dictionary describing the result from the request. The structure of the result varies depending on which API method initiated the request.

Return type:

dict, None

Raises:

CommandError – The request was not found, either expired, or never issued.
CommandError – If the API method that initiated this request resulted in an error.

ServerInterface.getRequestStatus(requestId)¶

Returns the status for an asynchronous request.

API methods whose name ends with Async represent asynchronous requests. These methods are sent a request which must be processed by the destination server, and return a requestId.

getRequestStatus() returns the current status for an asynchronous request, where the request is identified with its requestId. When an asynchronous request is complete, its result is available to getRequestResult().

Note

Allowing the results from asynchronous requests to be retrieved at an arbitrary time means that the result must be cached on the server. To avoid resource exhaustion, requests are set to expire after a period a time. Once expired, a request is no longer available.

The status field in the result indicates whether the request was successful. It may be one of three values:

pending: The request has not yet been processed.

success: The request was successful.

error: An unrecoverable error has terminated the request.

You may use the pending status to implement your own asynchronous poll behavior while your script waits for the request to be processed.

If the status is error then the errorMessage field contains a description of the error.

Parameters:: requestId (int, dict) – A request ID, as returned from any of the Async methods. Also allowed is the full dict from an Async method. The request ID is extracted from the requestId key.
Returns:: Request Structure
Return type:: dict
Raises:: CommandError – The request was not found, either expired, or never issued.

ServerInterface.getSandboxMappings()¶

Gets the sandbox mappings for all users.

Sandbox mappings can only be accessed by a superuser.

See Sandboxing in JetStream Server Documentation.

Returns:: Returns a dictionary that maps user names to sandbox mappings, where a sandbox mapping is a dictionary that maps sandbox names to sandbox paths.
Return type:: dict
Raises:: CommandError – If the user is not granted superuser privileges.

Added in version 1.5.0.

ServerInterface.getServerInfo()¶

Returns information about the connected server, including its name and API version.

Tip

This method does not require authentication.

Returns:: Server Information Structure
Return type:: dict

ServerInterface.getThirdPartyLicenses()¶

Returns the licenses for third-party software components used by JetStream.

Returns:: Library name, license text.
Return type:: dict

ServerInterface.getTransportRoutes()¶

Lists this server’s transport routing table.

Returns:: With a ‘routes’ key – a list of dicts with ‘prefix’ and ‘transport’. Prefixes come back in their canonical form, which may differ in spelling from what was sent (a bare address is returned as /32).
Return type:: dict
Raises:: CommandError – If the user is not granted superuser privileges

Added in version 3.0.0.

ServerInterface.getWranglers()¶

Gets the list of wrangler user and groups.

Wranglers can only be accessed by a superuser.

Returns:: Returns a dictionary that contains the list of wrangler users and list of wrangler groups.
Return type:: dict
Raises:: CommandError – If the user is not granted superuser privileges.

Added in version 2.5.0.

ServerInterface.listSyncFolders()¶

Lists the sync folder registrations the connected server holds.

This is the reconciliation primitive for registration drift: it reports what THIS server actually has registered, so a client can compare both ends of a pairing and detect a missed unregister, a server reset, or a re-imaged server. A regular session lists its own user’s registrations; a superuser session lists every user’s.

Returns:: {'syncFolders': [{'localPath': str, 'type': int, 'localUserId': str, 'localUsername': str, 'remotes': [{'uid': str, 'userId': str, 'username': str, 'path': str, 'direction': int, 'description': str, 'expiryTime': int}]}]}. type 0 is a watch folder (one or more remotes), 1 a bidirectional sync folder (exactly one remote). localPath is the canonical registration key in the CALLER’s coordinates: sandbox-relative for a sandboxed session (as the path was registered, e.g. /watch; registrations outside the session’s current sandbox roots are omitted), the raw server path otherwise.
Return type:: dict
Raises:: CommandError – If the user is not granted watch folder list permission.

Added in version 3.0.0.

ServerInterface.lsAsync(path, directory=None, calculateHashType=None)¶

Submits a request to retrieve a list of remote files, as visible to the connected server.

The result is provided as a dictionary with two keys:

path: The path to the directory being listed.

files: The stats for the requested files.

Each item in the “file” list is a dictionary containing the following keys:

name: The name of the file. To build the full path, join the parent path with this name.

type: Whether this file is a regular file (4), a directory (2) or a symlink (5).

size: The size, in bytes, of a regular file. For a directory or symlink, this will be 0 (zero).

mtime: The file’s last modification time as a UNIX Time (seconds since Epoch). Use time.ctime to convert to a human readable form.

mtimeus: The file’s last modification time in microseconds since Epoch (see Timestamps).

access: Combined read (1 << 2), write (1 << 1) and execute (1 << 0) bits that describes the current user’s access to this file.

hash: The hash value of file contents, if a valid calculateHashType is specified. Otherwise empty.

Parameters:

path (string) – The remote path to list on the connected server.
directory (bool) – (optional) If True, the specified path is a directory, and the result should return information about the directory itself, rather than the content of the directory.
calculateHashType (string) – (optional) Calculate a hash of each file. This may take some time as the file needs to be read. Currently supports “MD5” and “S3” as the has type.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Changed in version 2.3.0: Added mtimeus.

Changed in version 2.6.0: Added calculateHashType.

Changed in version 2.6.3: Added “MD5” type for calculateHashType.

ServerInterface.lsListAsync(pathList, statOnly=None, calculateHashType=None)¶

Submits a request to retrieve a list of remote files, as visible to the connected server.

The result is provided as a list of dictionary with two keys:

path: The path to the directory being listed.

files: The stats for the requested files.

The result list is a direct mapping of the input path list.

Each item in the “file” list is a dictionary containing the following keys:

name: The name of the file. To build the full path, join the parent path with this name.

type: Whether this file is a regular file (4), a directory (2) or a symlink (5).

size: The size, in bytes, of a regular file. For a directory or symlink, this will be 0 (zero).

mtime: The file’s last modification time as a UNIX Time (seconds since Epoch). Use time.ctime to convert to a human readable form.

mtimeus: The file’s last modification time in microseconds since Epoch (see Timestamps).

access: Combined read (1 << 2), write (1 << 1) and execute (1 << 0) bits that describes the current user’s access to this file.

hash: The hash value of file contents, if a valid calculateHashType is specified. Otherwise empty.

Parameters:

pathList (string list) – A list of remote pathes to list on the connected server.
statOnly (bool) – (optional) If True, when the specified path is a directory, and the result should return information about the directory itself, rather than the content of the directory.
calculateHashType (string) – (optional) Calculate a hash of each file. This may take some time as the file needs to be read. Currently supports “MD5” and “S3” as the has type.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

ServerInterface.lsRootsAsync()¶

Submits a request to retrieve a list of the root folders, as visible to the connected server.

The result is provided as a dictionary with two keys:

path: Representing the parent of the root folder, this will be an empty string.

files: The stats for each root folder.

Each item in the “file” list is a dictionary containing the following keys:

name: The name of the root folder.

type: 10, combining drive (8) and directory (2).

size: 0 (zero).

mtime: The folder’s last modification time. Use time.ctime to convert to a human readable form.

access: Combined read (1 << 2), write (1 << 1) and execute (1 << 0) bits that describes the current user’s access to this root.

Returns:: Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.
Return type:: dict

ServerInterface.mkFileAsync(path, size, fillRandom=False, modifyExisting=False)¶

Submits a request to create a new file on the connected server.

Parameters:

path (string) – The remote path to create on the connected server.
size (int) – The size of the newly created file.
fillRandom (bool) – Fill the file with random values.
modifyExisting (bool) – If set, replace any existing file with the same name, otherwise return success.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return None on success, or raise a CommandError.

Return type:

dict

Added in version 2.5.1.

ServerInterface.mkdirAsync(path)¶

Submits a request to create a new directory on the connected server, creating all parent directories as needed.

Tip

This will not fail if the requested directory already exists.

Parameters:

path (string) – The remote path to create on the connected server.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return None on success, or raise a CommandError.

Return type:

dict

Added in version 1.3.0.

Changed in version 1.8.0: Removed parents parameter. Parent directories are always created.

ServerInterface.mvAsync(path, newPath)¶

Submits a request to move or rename a path on the connected server.

Parameters:

path (string) – The remote path to create on the connected server.
newPath (string) – The new name for the path.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return None on success, or raise a CommandError.

Return type:

dict

Added in version 1.5.0.

ServerInterface.recvDiscoverPacketAsync(timeoutSeconds=None)¶

Creates a request to wait for an incoming receiver discovery packet.

A JetStream server may not know its address and port as visible to another. This function creates a token called a discover id and then waits for another server to send it a special packet that contains this data. Upon receipt, this server can derive the address of the server that sent the data. The server whose address is being discovered should send the discover id using sendDiscoverPacketAsync().

Parameters:

timeoutSeconds (float) – (optional) The number of seconds to wait for an incoming discover packet. If unused, a default timeout is used.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request. The dict additionally contains a discoverId key for use with sendDiscoverPacketAsync(). Ultimately, the result from the async function will be a Discover Packet Structure.

getRequestResult() will return dictionary Discover Packet Structure.

Return type:

dict

Example

# Server A wants to transfer data to B, but does not know B's public address.
# We do, however, have API access to both server A and B, and we know A's public address.
# Server A can "discover" B's address as follows:

# 1. Ask server A to listen for a discover packet.
>>> recvRequest = A.server.recvDiscoverPacketAsync()
>>> discoverId = recvRequest['discoverId']

# 2. Ask server B to send a discover packet using the return value form recvDiscoverPacketAsync.
>>> sendRequest = B.server.sendDiscoverPacketAsync(discoverId, A_addr, A_port)
>>> B.server.getRequestResult(sendRequest)
{'discoverPacketSent': True}

# 3. Wait for the discovery packet to be received or a timeout. On success, returns the address of B.
>>> A.server.getRequestResult(recvRequest)
{'port': 54946, 'address': '10.96.64.60'}

ServerInterface.registerSyncFolder(localPath, remoteUid, remoteUserId, remoteUser, remotePath, description='', expiryTime=0, pull=True, sync=False)¶

Registers a pairing between a local folder and a folder on a remote server.

The pairing is recorded on the connected server only; the remote server is never contacted. The owning identity is taken from the authenticated connection.

pull and sync set the new pairing’s direction: sync makes it bidirectional, otherwise pull selects Download (True) or Upload (False). Note that the other sync folder methods re-use these same two parameters to identify an existing pairing rather than to set anything — see validateSyncFolder().

Note

description and expiryTime are required on the wire, so passing None for either is not the same as omitting it: None is stripped from the request and the server rejects the call with “Required key not found”.

Parameters:

localPath (string) – The folder on the connected server to pair.
remoteUid (string) – The unique identifier of the remote server.
remoteUserId (string) – The user id, or token session id, of the user on the remote server.
remoteUser (string) – The user name of the user on the remote server. May be empty.
remotePath (string) – The folder on the remote server to pair with.
description (string) – (optional) A description of the pairing. Defaults to an empty string.
expiryTime (longint) – (optional) The time the pairing expires, in seconds since the epoch. 0 never expires.
pull (bool) – (optional) Sets the direction — True stores a Download pairing, False an Upload pairing. Ignored when sync is True. Default is True.
sync (bool) – (optional) Store a bidirectional sync folder instead of a one-way watch folder. Default is False.

Returns:

None

Raises:

CommandError – If the local folder path is invalid, the pairing is already registered, or the user is not granted watch folder create permission.

Added in version 2.9.6.

ServerInterface.resetSyncFolder()¶

Discards every sync folder registration on the connected server, for all users.

Sync folder registrations can only be reset by a superuser.

Returns:: None
Raises:: CommandError – If the user is not granted superuser privileges.

Added in version 2.9.6.

ServerInterface.rmAsync(path)¶

Submits a request to remove a path on the connected server. If the path refers to a directory, all files and directories under that path will be removed.

Parameters:

path (string) – The remote path to remove on the connected server.

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

getRequestResult() will return None on success, or raise a CommandError.

Return type:

dict

Added in version 1.5.0.

ServerInterface.sendDiscoverPacketAsync(discoverId, destinationAddress, destinationPort=None)¶

Sends a discovery packet to a waiting server.

A JetStream server may not know its address and port as visible to another. This function sends a special packet to another server to allow that server to discover this server’s receiving address and port. This function must be used in conjunction with recvDiscoverPacketAsync(). See that function for a usage example.

Parameters:

discoverId (int, dict) – A discover id as returned by recvDiscoverPacketAsync(). Also allowed is the full dict from recvDiscoverPacketAsync(). The discover ID is extracted from the discoverId key.
destinationAddress (str) – The host name or IP of the server that called recvDiscoverPacketAsync().
destinationPort (int) – (optional) The port of the serer that called recvDiscoverPacketAsync().

Returns:

Returns a Request Structure containing a requestId for this request. Use getRequestStatus() or getRequestResult() to monitor the status of the request.

Return type:

dict

Note

A discovery packet may be lost, so it is prudent to send several packets before concluding that the connection failed.

ServerInterface.setExternalAddress(address)¶

Sets the external address for the server.

The external address can be either a full qualified domain name or an IP address. This value is also prompted in client as an option for shared link creation.

Parameters:: address (string) – A full qualified domain name or an IP address for server external access.
Returns:: None
Raises:: CommandError – If the user is not granted superuser privileges

Added in version 2.6.3.

ServerInterface.setLicenseKeyAsync(key, validate=None)¶

Submits a request to set the license key for the server.

The license key can only be modified by a superuser.

Parameters:

key (string) – The new license key.
validate (bool) – Only set the license after validating the key with the license server.

Returns:

None

Raises:

CommandError – If the user is not granted superuser privileges.

Added in version 2.1.0.

ServerInterface.setSandboxMapping(userName, sandboxRoots)¶

Sets the sandbox mappings for a user.

Sandbox mappings can only be modified by a superuser.

A sandbox mapping is a dictionary that maps sandbox names to sandbox roots for a particular user. This sandbox names provide the roots paths available to the user (see lsRootsAsync()). All sandbox root paths are accessed by prefixing paths with the sandbox name followed by a colon.

Note

New sandbox mapping only take effect for new user sessions.

See Sandboxing in JetStream Server Documentation.

Parameters:

userName (string) – The user name of the user to sandbox. Note that the user name may be left blank to indicates the system sandbox. Any user who does not have a specific sandbox mapping will inherit the sandbox mapping from the system sandbox. The system sandbox may contain placeholders such as %u.
sandboxRoots (dict) – A dictionary of sandbox names to sandbox root paths. Sandbox names may be left blank to indicate a root of /. If sandbox roots is False, then the user is not sandboxed.

Returns:

None

Raises:

CommandError – If the user is not granted superuser privileges, a sandbox path is empty, or a sandbox name contains illegal characters.

Added in version 1.5.0.

ServerInterface.setTransportRoutes(routes)¶

Sets this server’s transport routing table.

The table decides which transport this server uses when it dials each peer. The transport is a property of the network path between two servers – what a link does to UDP is a fact about that link – so it is set here, on the server that does the dialling, by an administrator, rather than requested per transfer by a client.

REPLACES the whole table. Pass an empty list to clear it.

Parameters:: routes (list) – A list of dicts, each with ‘prefix’ and ‘transport’. prefix is an IPv4 CIDR such as 10.0.0.0/8, or a bare address meaning /32. transport is one of auto, cubic, bbr or tcp. The longest matching prefix wins, so a /32 exception can sit under a /8 policy. A prefix with bits set below its length is rejected, naming the value meant.
Returns:: None
Raises:: CommandError – If the user is not granted superuser privileges, or a route is malformed, duplicated, or the table is too large.

Added in version 3.0.0.

ServerInterface.setWebShareBranding(path=None)¶

Reload the branding document for the browser download pages.

The document holds the colors, the product name, the logo path and the link URLs. This command reads it again and rebuilds the pages. Downloads that are already running are not interrupted.

Parameters:: path (str) – A branding document to switch to. Leave it out to re-read the document that is already in effect, which is what you want after you edit the file in place.
Returns:: The response of the server.
Return type:: dict

Requires super user permission.

A document that cannot be read leaves the current appearance serving, and the response carries the reason.

ServerInterface.sleep(milliseconds)¶: Sleep for specified number of milliseconds.

ServerInterface.superuser()¶

Gives a user permission to access and modify all data, and access admin functions.

Only a user who has successfully called auth() with superuser eligible credentials will be granted superuser privileges. Users are eligible for superuser privileges if they share the same credentials as the user who started the server or have been listed as eligible during server configuration.

Superusers are always wranglers (see wrangler()).

Returns:: None
Raises:: CommandError – If the user is not granted superuser privileges.

ServerInterface.terminate()¶

Terminate the server.

The user must be a superuser before shutting down the server.

ServerInterface.unregisterSyncFolder(localPath, remoteUid, remoteUserId, remotePath, sync=False)¶

Removes a sync folder pairing.

Succeeds even when the local folder no longer exists on disk, so a pairing can still be removed after its folder has been deleted.

Note

Success means a pairing was actually removed. A call that matches nothing — unknown user, unknown local path, or unknown remote — raises OperationFailedError with “No such sync folder registration.” (This closed defect W16, which used to report success for all three.)

Note

Unlike validateSyncFolder(), removal ignores the pairing’s direction, so an Upload pairing is removed by a default call. There is deliberately no pull parameter.

Parameters:

localPath (string) – The folder on the connected server identifying the pairing.
remoteUid (string) – The unique identifier of the remote server.
remoteUserId (string) – The user id, or token session id, of the user on the remote server.
remotePath (string) – The folder on the remote server.
sync (bool) – (optional) Select the bidirectional sync folder rather than a watch folder. Default is False.

Returns:

None

Raises:

CommandError – If the user is not granted watch folder delete permission.

Added in version 2.9.6.

ServerInterface.updateAPIToken(token, timeLimitSeconds=None, description=None)¶

Updates the specified API token.

Parameters:

token (str, dict) – An API Token or Token Structure.
timeLimitSeconds – (optional) Number of seconds from now before this token expires.
description – (optional) A description of what this token represents.

Returns:

None

Raises:

CommandError – The API token was not found.

Added in version 2.6.0.

ServerInterface.updateBandwidthLimits(incomingLimitActive=None, incomingRateLimit=None, incomingMaxConnections=None, borrowOutgoing=None, outgoingLimitActive=None, outgoingRateLimit=None, borrowIncoming=None)¶

Sets limits on incoming and outgoing bandwidth utilization.

All parameters are optional. Any parameters which are unspecified or set to None will be unchanged.

Bandwidth limits can only be modified by a superuser.

Note

Bandwidth limits specified on the server command-line during startup become locked and cannot be changed. Attempting to update locked limits using this method will fail.

Warning

Compatibility note: When bandwidth control settings are enabled via the API or command line parameters on a JetStream server, clients prior to version 1.6.0 (API 22) will not be able to communicate with this server.

Parameters:

incomingLimitActive (bool) – Apply limits to incoming data.
incomingRateLimit (float) – The maximum rate that data will be received, in kilobits/second.
incomingMaxConnections (int) – The maximum number of incoming connections permitted.
borrowOutgoing (bool) – If there is an outgoing rate limit, allow unused outgoing bandwidth to be added to the incoming rate limit.
outgoingLimitActive (bool) – Apply limits to outgoing data.
outgoingRateLimit (float) – The maximum rate that data will be sent, in kilobits/second.
borrowIncoming (bool) – If there is an incoming rate limit, allow unused incoming bandwidth to be added to the outgoing rate limit.

Returns:

None

Raises:

CommandError – If the user is not granted superuser privileges, or if bandwidth changes are disallowed.

Added in version 1.6.0.

ServerInterface.updateGarbageCollectSettings(intervalSeconds=None, timeLimitSeconds=None)¶

Updates garbage collection.

All parameters are optional. Any parameters which are unspecified or set to None will be unchanged.

Garbage collection can only be modified by a superuser.

Parameters:

intervalSeconds (int) – The time, in seconds, between each garbage collection. Allowed range is from 60 (1 minute) to 2147483647 (about 68 years).
timeLimitSeconds (int) – The grace period, in seconds, to allow for items that are ready to be garbage collected. If 0, all eligible items will be discarded immediately. If non-zero, keep items that have been ready for garbage collection for less time than specified. Allowed range is from 0 to 2147483647 (about 68 years).

Returns:

Garbage Collect Structure

Return type:

dict

Raises:

CommandError – If the user is not granted superuser privileges.

Added in version 1.8.0.

ServerInterface.updateSchedulerParams(outgoingBudget=None, maxConcurrentTransfers=None, maxTransfersPerDestination=None)¶

Adjusts the urgency scheduler’s ceiling and admission while the server is running.

Every parameter is optional, but a call which names none is rejected rather than silently doing nothing. The budget is in megabits/second, unlike updateBandwidthLimits(), which is in kilobits/second and stays that way so that existing clients and deployed response files do not change meaning.

Scheduler parameters can only be modified by a superuser.

Note

These changes are never saved. A restart returns to the values the server was started with, so a response file remains the record of a box’s intended policy and a mistaken value is undone by restarting the service.

Parameters:

outgoingBudget (float) – The bandwidth transfers are admitted against, in megabits/second. This overrides both a configured outgoing rate limit and a measured estimate. Pass a negative value to clear the override and go back to whichever of those applies.
maxConcurrentTransfers (int) –
The most transfers the server runs at once, across every urgency level (API 62), and since API 63 the only thing that decides admission. This is a count, not a rate. 0 removes the limit. Pass a negative value to restore the value the server started with (--max-concurrent-transfers, default 10).

minTransferRate was a third parameter until API 63. It divided the budget into a transfer count; that count is now stated directly, here.
maxTransfersPerDestination (int) –
The most transfers to ANY ONE destination that run at once (API 64). Defaults to 1, so a second transfer to a peer the server is already sending to waits: both would ride the same connection, and splitting a pipe that is already full finishes neither sooner. 0 removes the per-destination limit and restores sharing to one peer. Pass a negative value to restore the value the server started with (--max-transfers-per-destination).

This is NOT interchangeable with maxConcurrentTransfers. That one bounds the whole server whatever transfers are going; this one bounds a single peer. The per-destination limit is applied first, so raising maxConcurrentTransfers never lets two transfers to one peer run together.

Returns:

None

Raises:

CommandError – If the user is not granted superuser privileges, if no parameter was given, or if a value is too small to be useful.

Added in version 3.0.0.

ServerInterface.updateSyncFolder(localPath, remoteUid, remoteUserId, remotePath, pull=True, sync=False, newDirection=None, newDescription=None, newExpiryTime=None)¶

Updates an existing sync folder pairing.

The first four parameters identify the existing pairing. Any new* parameter left unspecified is left unchanged on the server.

Warning

pull and sync do not change anything here — they identify which pairing to update. They become a direction (sync means bidirectional, otherwise pull True means Download and False means Upload) that must match the pairing’s stored direction. So updating an Upload pairing requires pull=False; with the default pull=True it fails with “Cannot find the matching sync folder to update.” even though the pairing exists. Use newDirection to change a direction.

Parameters:

localPath (string) – The folder on the connected server identifying the pairing.
remoteUid (string) – The unique identifier of the remote server.
remoteUserId (string) – The user id, or token session id, of the user on the remote server.
remotePath (string) – The folder on the remote server.
pull (bool) – (optional) Selects the Download pairing when True, the Upload pairing when False. A selector, not a setting — see the warning above. Default is True.
sync (bool) – (optional) Select the bidirectional sync folder rather than a watch folder. Default is False.
newDirection (int) – (optional) The new transfer direction: 0 for Download, 1 for Upload, 2 for Bidirection. The server does not range-check this value, and it rejects a watch folder set to Bidirection or a sync folder set away from it.
newDescription (string) – (optional) The new description. Pass an empty string to clear it.
newExpiryTime (longint) – (optional) The new expiry time, in seconds since the epoch. 0 never expires.

Returns:

None

Raises:

CommandError – If no such pairing exists, or the user is not granted watch folder change permission.

Added in version 2.9.6.

ServerInterface.validateSyncFolder(localPath, remoteUid, remoteUserId, remotePath, pull=True, sync=False, checkUserWatch=False)¶

Checks whether a sync folder pairing is registered.

Warning

checkUserWatch inverts the success semantics of this method. With checkUserWatch set, finding a registration is a failure (“Remote user has already watched this folder.”) and finding none is success — it is a pre-registration availability check, not a lookup.

Warning

pull and sync identify which pairing to look for; they are not settings. They become a direction (sync means bidirectional, otherwise pull True means Download and False means Upload) that must match the pairing’s stored direction, so a registered Upload pairing is reported as not registered unless pull=False is passed.

Note

A failed lookup (without checkUserWatch) reports “No such sync folder registration.” after the “Failed to validate sync folder: “ prefix. (This closed defect W44, which reported the bare prefix with no reason.) Type conflicts — e.g. validating a watch folder against a registered sync folder — keep their own more specific messages.

Parameters:

localPath (string) – The folder on the connected server identifying the pairing.
remoteUid (string) – The unique identifier of the remote server.
remoteUserId (string) – The user id, or token session id, of the user on the remote server.
remotePath (string) – The folder on the remote server.
pull (bool) – (optional) Selects the Download pairing when True, the Upload pairing when False. A selector, not a setting — see the warning above. Default is True.
sync (bool) – (optional) Select the bidirectional sync folder rather than a watch folder. Default is False.
checkUserWatch (bool) – (optional) Invert the check, as described above. Default is False.

Returns:

None

Raises:

CommandError – If the pairing is not registered, or is already registered when
checkUserWatch` is set, or the user is not granted watch folder list permission –

Added in version 2.9.6.

ServerInterface.wrangler()¶

Gives a user permission to access and modify all data.

Only a user who has successfully called auth() with wrangler eligible credentials will be granted wrangler privileges. Users are eligible for wrangler privileges if they have been given wrangler permissions by a superuser using the addWrangler() function.

Returns:: None
Raises:: CommandError – If the user is not granted wrangler privileges.

Added in version 2.5.0.