.\" DO NOT MODIFY THIS FILE!  It was generated by setup.py 1.2.
.TH REXEC 3 "21 March 2023" "NFStest 3.2" "rexec 1.2"
.SH NAME
nfstest.rexec - Remote procedure module
.SH DESCRIPTION

Provides a set of tools for executing a wide range commands, statements,
expressions or functions on a remote host by running a server process
on the remote host serving requests without disconnecting. This allows
for a sequence of operations to be done remotely and not losing state.
A file could be opened remotely, do some other things and then write
to the same opened file without opening the file again.

The remote server can be executed as a different user by using the sudo
option and sending seteuid. The server can be executed locally as well
using fork when running as the same user or using the shell when the
sudo option is used.

In order to use this module the user id must be able to 'ssh' to the
remote host without the need for a password.
.SH CLASSES
.SS class RemoteServer(builtins.object)
.nf
.P
.B Methods defined here:
---------------------
.P
.B __del__(self)
Destructor
.P
.B __init__(self, port, logfile=None)
Remote procedure server
.P
.B log(self, msg)
Write message to log file
.P
.B start(self)
.fi
.SS class Rexec(baseobj.BaseObj)
.nf
Rexec object

       Rexec() -> New remote procedure object

       Arguments:
           servername:
               Name or IP address of remote server
           logfile:
               Name of logfile to create on remote server
           sudo:
               Run remote server as root

       Usage:
           from nfstest.rexec import Rexec

           # Function to be defined at remote host
           def add_one(n):
               return n + 1

           # Function to be defined at remote host
           def get_time(delay=0):
               time.sleep(delay)
               return time.time()

           # Create remote procedure object
           x = Rexec("192.168.0.85")

           # Define function at remote host
           x.rcode(add_one)

           # Evaluate the expression calling add_one()
           out = x.reval("add_one(67)")

           # Run the function with the given argument
           out = x.run("add_one", 7)

           # Run built-in functions
           import time
           out = x.run(time.time)

           # Import libraries and symbols
           x.rimport("time", ["sleep"])
           x.run("sleep", 2)

           # Define function at remote host -- since function uses the
           # time module, this module must be first imported
           x.rimport("time")
           x.rcode(get_time)

           # Evaluate the expression calling get_time()
           out = x.reval("get_time()")

           # Run the function with the given argument
           out = x.run("get_time", 10)

           # Open file on remote host
           fd = x.run(os.open, "/tmp/testfile", os.O_WRONLY|os.O_CREAT|os.O_TRUNC)
           count = x.run(os.write, fd, "hello there
\t")
           x.run(os.close, fd)

           # Use of positional arguments
           out = x.run("get_time", 2)

           # Use of named arguments
           out = x.run("get_time", delay=2)

           # Use of NOWAIT option for long running functions so other things
           # can be done while waiting
           x.run("get_time", 2, NOWAIT=True)
           while True:
               # Poll every 0.1 secs to see if function has finished
               if x.poll(0.1):
                   # Get results
                   out = x.results()
                   break

           # Create remote procedure object as a different user
           # First, run the remote server as root
           x = Rexec("192.168.0.85", sudo=True)
           # Then set the effective user id
           x.run(os.seteuid, 1000)

.P
.B Methods defined here:
---------------------
.P
.B __del__(self)
Destructor
.P
.B __init__(self, servername=None, logfile=None, sudo=False, timeout=30.0)
Constructor

Initialize object's private data.

.RS
.TP
.B
servername:
Host name or IP address of host where remote server will run
[Default: None (run locally)]
.TP
.B
logfile:
Pathname of log file to be created on remote host
[Default: None]
.TP
.B
sudo:
Run remote procedure server as root
[Default: False]
.TP
.B
timeout:
Timeout for synchronous calls
[Default: 30.0]
.RE
.P
.B close(self)
Close connection to remote server
.P
.B poll(self, timeout=0)
Return whether there is any data available to be read

.RS
.TP
.B
timeout:
Maximum time in seconds to block, if timeout is None then
an infinite timeout is used
.RE
.P
.B rcode(self, code)
Define function on remote server
.P
.B results(self, xid=None)
Return pending results
.P
.B reval(self, expr)
Evaluate expression on remote server
.P
.B rexec(self, expr)
Execute statement on remote server
.P
.B rimport(self, module, symbols=[])
Import module on remote server

.RS
.TP
.B
module:
Module to import in the remote server
.TP
.B
symbols:
If given, import only these symbols from the module
.RE
.P
.B run(self, *kwts, **kwds)
Run function on remote server

The first positional argument is the function to be executed.
All other positional arguments and any named arguments are treated
as arguments to the function
.P
.B wait(self, objlist=None, timeout=0)
Return a list of Rexec objects where data is available to be read

.RS
.TP
.B
objlist:
List of Rexec objects to poll, if not given use current object
.TP
.B
timeout:
Maximum time in seconds to block, if timeout is None then
an infinite timeout is used
.RE
.fi
.SH SEE ALSO
.BR baseobj(3)

.SH BUGS
No known bugs.
.SH AUTHOR
Jorge Mora (mora@netapp.com)