path: root/docs/manpages/rpcclient.1

.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "RPCCLIENT" "1" "03 april 2003" "" ""

.SH NAME
rpcclient \- tool for executing client side  MS-RPC functions
.SH SYNOPSIS

\fBrpcclient\fR [ \fB-A authfile\fR ] [ \fB-c <command string>\fR ] [ \fB-d debuglevel\fR ] [ \fB-h\fR ] [ \fB-l logfile\fR ] [ \fB-N\fR ] [ \fB-s <smb config file>\fR ] [ \fB-U username[%password]\fR ] [ \fB-W workgroup\fR ] [ \fB-N\fR ] [ \fB-I destinationIP\fR ] \fBserver\fR

.SH "DESCRIPTION"
.PP
This tool is part of the \fBSamba\fR(7) suite.
.PP
\fBrpcclient\fR is a utility initially developed
to test MS-RPC functionality in Samba itself.  It has undergone 
several stages of development and stability.  Many system administrators
have now written scripts around it to manage Windows NT clients from 
their UNIX workstation. 
.SH "OPTIONS"
.TP
\fBserver\fR
NetBIOS name of Server to which to connect. 
The server can be  any SMB/CIFS server.  The name is 
resolved using the   \fIname resolve order\fR line from \fBsmb.conf\fR(5).
.TP
\fB-c|--command='command string'\fR
execute semicolon separated commands (listed 
below)) 
.TP
\fB-I IP-address\fR
\fIIP address\fR is the address of the server to connect to. 
It should be specified in standard "a.b.c.d" notation. 

Normally the client would attempt to locate a named 
SMB/CIFS server by looking it up via the NetBIOS name resolution 
mechanism described above in the \fIname resolve order\fR 
parameter above. Using this parameter will force the client
to assume that the server is on the machine with the specified IP 
address and the NetBIOS name component of the resource being 
connected to will be ignored. 

There is no default for this parameter. If not supplied, 
it will be determined automatically by the client as described 
above. 
.TP
\fB-V\fR
Prints the version number for 
\fBsmbd\fR.
.TP
\fB-s <configuration file>\fR
The file specified contains the 
configuration details required by the server.  The 
information in this file includes server-specific
information such as what printcap file to use, as well 
as descriptions of all the services that the server is 
to provide. See \fIsmb.conf(5)\fR for more information.
The default configuration file name is determined at 
compile time.
.TP
\fB-d|--debug=debuglevel\fR
\fIdebuglevel\fR is an integer 
from 0 to 10.  The default value if this parameter is 
not specified is zero.

The higher this value, the more detail will be 
logged to the log files about the activities of the 
server. At level 0, only critical errors and serious 
warnings will be logged. Level 1 is a reasonable level for
day to day running - it generates a small amount of 
information about operations carried out.

Levels above 1 will generate considerable 
amounts of log data, and should only be used when 
investigating a problem. Levels above 3 are designed for 
use only by developers and generate HUGE amounts of log
data, most of which is extremely cryptic.

Note that specifying this parameter here will 
override the log
level file.
.TP
\fB-l|--logfile=logbasename\fR
File name for log/debug files. The extension
".client" will be appended. The log file is
never removed by the client.
.TP
\fB-N\fR
If specified, this parameter suppresses the normal
password prompt from the client to the user. This is useful when
accessing a service that does not require a password. 

Unless a password is specified on the command line or
this parameter is specified, the client will request a
password.
.TP
\fB-k\fR
Try to authenticate with kerberos. Only useful in
an Active Directory environment.
.TP
\fB-A|--authfile=filename\fR
This option allows
you to specify a file from which to read the username and
password used in the connection.  The format of the file is


.nf
username = <value>
password = <value>
domain   = <value>
.fi

Make certain that the permissions on the file restrict 
access from unwanted users. 
.TP
\fB-U|--user=username[%password]\fR
Sets the SMB username or username and password. 

If %password is not specified, the user will be prompted. The
client will first check the \fBUSER\fR environment variable, then the
\fBLOGNAME\fR variable and if either exists, the
string is uppercased. If these environmental variables are not
found, the username GUEST is used. 

A third option is to use a credentials file which
contains the plaintext of the username and password.  This
option is mainly provided for scripts where the admin does not
wish to pass the credentials on the command line or via environment
variables. If this method is used, make certain that the permissions
on the file restrict access from unwanted users.  See the
\fI-A\fR for more details. 

Be cautious about including passwords in scripts. Also, on
many systems the command line of a running process may be seen
via the \fBps\fR command.  To be safe always allow
\fBrpcclient\fR to prompt for a password and type
it in directly. 
.TP
\fB-n <primary NetBIOS name>\fR
This option allows you to override
the NetBIOS name that Samba uses for itself. This is identical
to setting the \fINetBIOS
name\fR parameter in the \fBsmb.conf\fR(5) file.  However, a command
line setting will take precedence over settings in
\fBsmb.conf\fR(5).
.TP
\fB-i <scope>\fR
This specifies a NetBIOS scope that
\fBnmblookup\fR will use to communicate with when
generating NetBIOS names. For details on the use of NetBIOS
scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes are
\fBvery\fR rarely used, only set this parameter
if you are the system administrator in charge of all the
NetBIOS systems you communicate with.
.TP
\fB-W|--workgroup=domain\fR
Set the SMB domain of the username.   This
overrides the default domain which is the domain defined in
smb.conf.  If the domain specified is the same as the servers 
NetBIOS name, it causes the client to log on using the servers local 
SAM (as opposed to the Domain SAM). 
.TP
\fB-O socket options\fR
TCP socket options to set on the client
socket. See the socket options parameter in
the \fBsmb.conf\fR(5) manual page for the list of valid
options. 
.TP
\fB-h|--help\fR
Print a summary of command line options.
.SH "COMMANDS"
.PP
\fBLSARPC\fR
.TP 0.2i
\(bu
\fBlsaquery\fR
.TP 0.2i
\(bu
\fBlookupsids\fR - Resolve a list 
of SIDs to usernames.
.TP 0.2i
\(bu
\fBlookupnames\fR - Resolve a list 
of usernames to SIDs.
.TP 0.2i
\(bu
\fBenumtrusts\fR
.PP
.PP
\fBSAMR\fR
.TP 0.2i
\(bu
\fBqueryuser\fR
.TP 0.2i
\(bu
\fBquerygroup\fR
.TP 0.2i
\(bu
\fBqueryusergroups\fR
.TP 0.2i
\(bu
\fBquerygroupmem\fR
.TP 0.2i
\(bu
\fBqueryaliasmem\fR
.TP 0.2i
\(bu
\fBquerydispinfo\fR
.TP 0.2i
\(bu
\fBquerydominfo\fR
.TP 0.2i
\(bu
\fBenumdomgroups\fR
.PP
.PP
\fBSPOOLSS\fR
.TP 0.2i
\(bu
\fBadddriver <arch> <config>\fR 
- Execute an AddPrinterDriver() RPC to install the printer driver 
information on the server.  Note that the driver files should 
already exist in the directory returned by  
\fBgetdriverdir\fR.  Possible values for 
\fIarch\fR are the same as those for 
the \fBgetdriverdir\fR command.
The \fIconfig\fR parameter is defined as 
follows: 


.nf
Long Printer Name:\\
Driver File Name:\\
Data File Name:\\
Config File Name:\\
Help File Name:\\
Language Monitor Name:\\
Default Data Type:\\
Comma Separated list of Files
.fi

Any empty fields should be enter as the string "NULL". 

Samba does not need to support the concept of Print Monitors
since these only apply to local printers whose driver can make
use of a bi-directional link for communication.  This field should 
be "NULL".   On a remote NT print server, the Print Monitor for a 
driver must already be installed prior to adding the driver or 
else the RPC will fail. 
.TP 0.2i
\(bu
\fBaddprinter <printername> 
<sharename> <drivername> <port>\fR 
- Add a printer on the remote server.  This printer 
will be automatically shared.  Be aware that the printer driver 
must already be installed on the server (see \fBadddriver\fR) 
and the \fIport\fRmust be a valid port name (see
\fBenumports\fR.
.TP 0.2i
\(bu
\fBdeldriver\fR - Delete the 
specified printer driver for all architectures.  This
does not delete the actual driver files from the server,
only the entry from the server's list of drivers.
.TP 0.2i
\(bu
\fBenumdata\fR - Enumerate all 
printer setting data stored on the server. On Windows NT  clients, 
these values are stored  in the registry, while Samba servers 
store them in the printers TDB.  This command corresponds
to the MS Platform SDK GetPrinterData() function (* This
command is currently unimplemented).
.TP 0.2i
\(bu
\fBenumjobs <printer>\fR 
- List the jobs and status of a given printer. 
This command corresponds to the MS Platform SDK EnumJobs() 
function (* This command is currently unimplemented).
.TP 0.2i
\(bu
\fBenumports [level]\fR 
- Executes an EnumPorts() call using the specified 
info level. Currently only info levels 1 and 2 are supported. 
.TP 0.2i
\(bu
\fBenumdrivers [level]\fR 
- Execute an EnumPrinterDrivers() call.  This lists the various installed 
printer drivers for all architectures.  Refer to the MS Platform SDK 
documentation for more details of the various flags and calling 
options. Currently supported info levels are 1, 2, and 3.
.TP 0.2i
\(bu
\fBenumprinters [level]\fR 
- Execute an EnumPrinters() call.  This lists the various installed 
and share printers.  Refer to the MS Platform SDK documentation for 
more details of the various flags and calling options. Currently
supported info levels are 0, 1, and 2.
.TP 0.2i
\(bu
\fBgetdata <printername>\fR 
- Retrieve the data for a given printer setting.  See 
the  \fBenumdata\fR command for more information.  
This command corresponds to the GetPrinterData() MS Platform 
SDK function (* This command is currently unimplemented). 
.TP 0.2i
\(bu
\fBgetdriver <printername>\fR 
- Retrieve the printer driver information (such as driver file, 
config file, dependent files, etc...) for 
the given printer. This command corresponds to the GetPrinterDriver()
MS Platform  SDK function. Currently info level 1, 2, and 3 are supported.
.TP 0.2i
\(bu
\fBgetdriverdir <arch>\fR 
- Execute a GetPrinterDriverDirectory()
RPC to retrieve the SMB share name and subdirectory for 
storing printer driver files for a given architecture.  Possible 
values for \fIarch\fR are "Windows 4.0" 
(for Windows 95/98), "Windows NT x86", "Windows NT PowerPC", "Windows
Alpha_AXP", and "Windows NT R4000". 
.TP 0.2i
\(bu
\fBgetprinter <printername>\fR 
- Retrieve the current printer information.  This command 
corresponds to the GetPrinter() MS Platform SDK function. 
.TP 0.2i
\(bu
\fBopenprinter <printername>\fR 
- Execute an OpenPrinterEx() and ClosePrinter() RPC 
against a given printer. 
.TP 0.2i
\(bu
\fBsetdriver <printername>
<drivername>\fR
- Execute a SetPrinter() command to update the printer driver
associated with an installed printer.  The printer driver must
already be correctly installed on the print server.  

See also the \fBenumprinters\fR and 
\fBenumdrivers\fR commands for obtaining a list of
of installed printers and drivers.
.PP
\fBGENERAL OPTIONS\fR
.TP 0.2i
\(bu
\fBdebuglevel\fR - Set the current
debug level used to log information.
.TP 0.2i
\(bu
\fBhelp (?)\fR - Print a listing of all 
known commands or extended help  on a particular command. 
.TP 0.2i
\(bu
\fBquit (exit)\fR - Exit \fBrpcclient
\fR.
.SH "BUGS"
.PP
\fBrpcclient\fR is designed as a developer testing tool 
and may not be robust in certain areas (such as command line parsing).  
It has been known to  generate a core dump upon failures when invalid 
parameters where passed to the interpreter. 
.PP
From Luke Leighton's original rpcclient man page:
.PP
\fBWARNING!\fR The MSRPC over SMB code has 
been developed from examining  Network traces. No documentation is 
available from the original creators  (Microsoft) on how MSRPC over 
SMB works, or how the individual MSRPC services  work. Microsoft's 
implementation of these services has been demonstrated  (and reported) 
to be... a bit flaky in places. 
.PP
The development of Samba's implementation is also a bit rough, 
and as more of the services are understood, it can even result in 
versions of \fBsmbd\fR(8) and \fBrpcclient\fR(1) that are incompatible for some commands or  services. Additionally, 
the developers are sending reports to Microsoft,  and problems found 
or reported to Microsoft are fixed in Service Packs,  which may 
result in incompatibilities.
.SH "VERSION"
.PP
This man page is correct for version 3.0 of the Samba 
suite.
.SH "AUTHOR"
.PP
The original Samba software and related utilities 
were created by Andrew Tridgell. Samba is now developed
by the Samba Team as an Open Source project similar 
to the way the Linux kernel is developed.
.PP
The original rpcclient man page was written by Matthew 
Geddes, Luke Kenneth Casson Leighton, and rewritten by Gerald Carter.  
The conversion to DocBook for Samba 2.2 was done by Gerald 
Carter. The conversion to DocBook XML 4.2 for Samba 3.0 was
done by Alexander Bokovoy.