A.3. Samba Client Programs This section lists the command-line options and subcommands provided by each nondaemon program in the Samba distribution. A.3.1. Common Options Many Samba commands share groups of command-line parameters. The common options fall into three categories: A.3.1.1. General options
-?|--help Print usage information for the command.
--usage Print a brief command usage description.
-d|--debuglevel debug_level Set the debug (sometimes called logging) level. The level normally ranges from 0 to 10. Specifying the value on the command line overrides the value specified in the smb.conf file. Debug level 0 logs only the most important messages; level 1 is normal; levels 3 and above are primarily for debugging Samba and can slow the tool considerably.
-l|--log-basename log_directory Send the log messages to somewhere other than the location compiled into the executable or specified in the smb.conf file. If the directory does not exist, Samba's compiled-in default will be used.
-s|--configfile configuration_file The location of the Samba configuration file, overriding any compile time default location.
-V|--version Print the program's version information. A.3.1.2. Authentication options
-A|--authentication-file filename Specify a file containing the user credentials to be used for the connection request rather than passing the information as command-line parameters. Parameters in the file can be one of three keywords: username, password, or domain. Each keyword is followed by an equal sign (=) and the option's value. The format of the file is as follows: username = value password = value domain = value
Parameters defined in the authentication file take precedence over their command-line counterparts. The permissions on the file should be very restrictive (0600, for example) to prevent access by unwanted users. You can find examples of authentication files in Chapter 11.
-k|--kerberos Enable Kerberos 5 authentication when connecting to the remote server. This requires that you have previously obtained a TGT using the kinit command. When you enable Kerberos authentication, the -U and -A options will be ignored. More information about Kerberos can be found in Chapter 10.
-N|--no-pass Request an anonymous connection.
-P|--machine-pass Use the machine's trust account when connecting to remote servers.
-S|--signing=[on,off,required] Specify the SMB signing policy to use when connecting to a remote server. The keyword on enables negotiation of SMB signing, and required makes the capability mandatory. To disable client support entirely, even if SMB signing is supported by the server, set the parameter to off.
-U|--user name Specify the user name to use in the authentication request when connecting to a remote server. You can append the user's password to the login name by specifying a percent sign (%) and then the passphrase. A.3.1.3. Connection options
-i|--scope netbios_scope The NetBIOS scope value to be used when communicating with other NetBIOS hosts. You should never use this option unless absolutely required by the remote server.
-n|--netbiosname name The calling name to be used in the NetBIOS session request. This is not needed for most network environments.
-O|--socket-options option_list Define a list of socket options to be used in the client connection. The range of options will vary from system to system and is described fully in the manpage for the setsockopt( ) function call. This parameter is normally useful when testing performance and running benchmarks.
-W|--workgroup name The list client's workgroup (or domain) name. This is useful when you need to specify a user's domain as part of the authentication requests.
The eventlogadm command is used to manage Samba's EventLog tdb files and related settings. Its primary use is to write new EventLog entries. Unlike other Samba command-line tools, eventlogadm does not share any of the common options. Eventlogs are covered in Chapter 9.
Command synopsis -
eventlogadm [options]
Options -
-d Enable the tool's debug output.
-h Print command-line usage.
-o write EventLogName Write a a log entry to the file EventLogName.tdb in Samba's lock directory. The logfile name must be listed in the eventlog list parameter in smb.conf.
-o addsource EventLogName SourceName MessageFileDLL The Windows message file DLL location that will be downloaded by Windows clients when viewing Eventlog records.
This Perl script reports information about systems on the subnet that respond to SMB name-query requests. The report includes the IP address, NetBIOS name, workgroup/domain, and operating system of each system. The output from findsmb looks like this: $ ./findsmb *=DMB +=LMB IP ADDR NAME WORKGROUP/OS/VERSION --------------------------------------------------------------------- 192.168.1.46 FIR [VALE] [Unix] [Samba 3.0.20b] 192.168.1.47 OAK +[COLOR] [Unix] [Samba 3.0.14a] 192.168.1.74 MAPLE *[VALE] [Unix] [Samba 3.0.22] 192.168.1.101 SPUD *[AD] [Windows 5.0] [Windows 2000 LAN Manager]
The system with an asterisk (*) in front of its workgroup name is the domain master browser for the workgroup/domain, and the system with a plus sign (+) preceding its workgroup name is the local master browser.
Command synopsis -
findsmb [options]
Options -
-B Specify the broadcast address when calling nmblookup to resolve master browsers and server names. If no subnet broadcast address is supplied, findsmb will look on the local subnet.
-d|-D Enable debug messages in the findsmb code.
-r Enable the root-only flag when calling nmblookup. This is useful when locating Windows 95 hosts on the network.
The net command is a program with a syntax similar to the MS-DOS/Windows command of the same name. It is used for performing various administrative functions related to Windows networking, which can be executed either locally or on a remote system. This utility has the same general, authentication, and connection command-line options as many Samba tools.
Command synopsis -
net [method] function [target_options] [misc_options]
The function argument is made up of one or more space-separated words. In Windows terminology, it is sometimes referred to as a function with options. By default, the action is performed on the local system. The target_options argument can be used to specify a remote system (either by hostname or IP address), a domain, or a workgroup. Depending on the function, the method argument can be optional, required, or disallowed. It specifies one of three methods for performing the operation specified by the rest of the command. It can be ads (Active Directory), rpc (Microsoft's DCE/ RPC), or rap (Microsoft's original SMB remote procedure call). To determine which methods (if any) can be used with a function, the net help ads, net help rap, and net help rpc commands can be used to list the functions for each method. Chapter 11 contains more information on the net command as well as examples.
Target options -
-S|--server hostname Specify the remote system using a hostname or NetBIOS name.
-I|--ipaddress ip_address Specify the remote system using its IP address.
-w|--workgroup workgroup Specify the name of the target domain or workgroup.
Miscellaneous options -
-d|--debuglevel level Define Samba's log for displaying information debug messages.
-l|--long Long listing mode. This is provided for functions that print informational listings.
-n|--myname name The NetBIOS name for the client.
-p|--port port The port number to use when connecting to the server.
-P|--machine-pass Use the machine's trust account when connecting to remote servers.
-s|--configfile configuration_file The location of the Samba configuration file, overriding any compile time default location.
-U|--user name The user name to use in the authentication request when connecting to a remote server. You can append the user's password to the login name by specifying a percent sign (%) and then the passphrase.
-V|--version Print the Samba's version information.
-W|--workgroup name The list client's workgroup (or domain) name. This is useful when you need to specify a user's domain as part of the authentication requests.
RAP functions -
domain Enumerate the list of known browsing domains and browse masters.
file [user|close|info] Enumerate all open files or ones opened by a specific user. You can also request the server to close a given file.
group [add|delete] The basic form of the group command allows you enumerate groups on the server as well as create new ones or remove existing ones.
groupmember Manage group membership.
password username old_password new_password Send a user password change request for username.
printq [list|delete] Enumerate jobs in a print queue or remove specific jobs.
server Enumerate hosts in the server's workgroup.
session [close|info] Enumerate open sessions on the server. You may also request additional information regarding a specific session or request that the server close the active session.
share Enumerate shares on the server similar to the smbclient -L command.
user [add|delete|rename|info] Basic user management functions such as enumerating, creating, removing, and renaming accounts.
validate username password Authenticate a username/password pair against the server's list of accounts.
RPC functions -
abortshutdown Abort the shutdown of a remote server.
changetrustpw Change the machine's trust account password.
file [user|close] Enumerate all open files or ones opened by a specific user. You can also request the server to close a given file.
getsid Retrieve the domain SID from the remote server specified using the --server option and store the result in secrets.tdb. This is often used as part of the net rpc vampire process.
group [add|delete|members|addmem|delmem] The basic form of the group command allows you enumerate groups on the server as well as create new ones or remove existing ones. The membership-related subcommands can be used to list or modify the collection of users belonging to a group.
info Print information about the remote server and its domain.
join Join a Windows or Samba domain for use with security = domain configurations. If the -U username%password option is included, the specified username and password will be used as the administrative account required for authenticating with the PDC. If the -U option is not included, this function can be used only to join the computer to the domain after the computer account has been created using the Server Manager.
password username new_password Set the password for a user account. You must specify an account with administrative rights using the --user option in order to force the password change.
printer [list|driver|publish|migrate] Enumerate printers or drivers installed on the server. If the remote host is joined to an AD domain, you can also have the server publish the printer's information in the directory service. The final option allows you to migrate printers, drivers, or settings from the remote server to the local Samba host.
registry [enumerate|save|dump] Simple interface for viewing remote registry files as well as saving them to a local file. This is an experimental feature currently.
rights [list|grant|revoke] Manage the user privilege assignments on a server. You can enumerate the available rights and assignments. The grant and revoke subcommands allow you to add and remove assignments respectively. Chapter 5 discusses user rights in detail.
service [list|stop|start|pause|resume|status] Manage a server's collection of services. This includes listing installed services and their current state as well as toggling the state of running, paused. or stopped services. Chapter 9 covers the steps to setup service control on Samba hosts.
share [add|delete|allowedusers|migrate] Manage file shares on the server. This includes listing active shares as well as creating new ones and unsharing existing ones. You can also migrate shares and files from the remote server to the local Samba host. Share management is discussed in Chapters 9 and 11.
shutdown Shut down a server. This function accepts the -r, -f, -t, and -c miscellaneous options. The -r option (which can also be specified as --reboot) requests that the system reboot after shutting down. The -f option (which can also be specified as --force) forces a shutdown. The -t timeout option (which can also be specified as --timeout=number) specifies the number of seconds to wait before shutting down, and the -c comment option (which can also be specified as --comment= string) can be used to specify a message to the client user. On Windows, the comment appears in the Message area in the System Shutdown dialog box.
testjoin Validate the local host's machine trust account password in the domain.
trustdom [list|add|del|establish|revoke] Manage domain trust relationships on a Samba domain controller. Chapter 9 discusses the configuration details for establishing domain trusts.
user [add|delete|rename] Basic user management functions such as enumerating, creating, removing, and renaming accounts.
vampire Migrate user, group, and computer accounts from a Windows NT Primary Domain Controller onto a Samba PDC. Successfully running this command requires a large amount of prior server configuration. Chapter 9 covers the complete steps for migrating from a Windows domain to Samba.
ADS functions -
changetrustpw Change the machine's trust account password.
group [add|delete] Enumerate groups on the server, as well as create new ones or remove existing ones.
info Print information about the Active Directory server.
join Join the local system to the Active Directory realm. This function must be used if your server is configured to make use of security = ads and Kerberos authentication.
keytab [create|add|flush] Manage a local Kerberos keytab file based on Samba's machine trust account password and domain membership. This incldues creating an initial keytab file from the information stored in secrets.tdb as well as adding new service principal names to the machine's account in AD. Chapter 10 explains how to use keytab files with Samba member servers in an AD environment.
leave Remove the local system from the Active Directory realm. Newer versions of net will disable the account rather than removing it.
lookup Send a CLDAP request to an AD domain controller and display the query results.
password username@ REALM Change the Active Directory password for the user specified by username@REALM. The administrative account authentication information is specified with the -U option. The Active Directory realm must be supplied in all uppercase.
printer [search|info|publish|remove] Manage printer information stored in AD. This does not affect printers or print shares, but only the information about the printer stored in the directory services.
search expr attrib Perform a raw Active Directory search, using the standard LDAP search expression and attributes specified by the expr and attrib arguments, respectively.
status Print details about the Active Directory computer account of the system.
testjoin Validate the local host machine's trust account password in the domain.
user [add|delete|rename] Basic user management functions such as enumerating, creating, removing, and renaming accounts.
Miscellaneous functions -
cache [add|set|del|flush|get|search|list] A simple database management tool for Samba's gencache.tdb. This can be helpful, for example, when tracking down name resolution errors caused by incorrect cached information.
getlocalsid [ name] Print the machine's local SID stored in secrets.tdb. You may supply an optional domain name, in which case the SID for that name will be displayed instead.
groupmap [add|modify|delete] Manage Samba's group mapping table. You can establish new mapping records and update or remove existing ones. Samba's group mapping feature is discussed in Chapter 5.
help [ command] Print the help text for a specific command. Not all commands have help text available.
idmap [dump|restore] Backup the idmap table to a text file or restore the table from a previous backup. The dump subcommand prints the table contexts to standard output.
lookup [host|ldap|kdc|master] Perform basic name resolution queries for determining the address of hostnames, directory servers, Kerberos KDCs, and local master browsers.
time [set|system|zone] Display the system timein Unix date command formaton the target system. You can use the set and system subcommands to update the local host's clock.
setlocalsid Define the SID to store for the local machine in secrets.tdb.
The nmblookup program is a client program that allows command-line access to NetBIOS name service for resolving NetBIOS computer names into IP addresses. The program works by broadcasting its queries on the local subnet until a machine with the specified name responds. You can think of it as a Windows analog of nslookup or dig. This is useful for looking up regular computer names, as well as special-purpose names, such as _ _MSBROWSE_ _. If you wish to query for a particular type of NetBIOS name, add the NetBIOS type to the end of the name, using the format netbios_name#dd, where dd is the hexidecimal representation of the resource byte.
Command synopsis -
nmblookup [options] netbios_name [netbios_name]
The nmblookup tool supports both the general and the connection option sets described in the beginning of this section.
Options -
-A|--lookup-by-ip Interpret netbios_name as an IP address and does a node status query on it.
-B|--broadcast broadcast_address Send the query to the given broadcast address. The default is to send broadcast queries using all detected network interfaces.
-f|--flags Print the NetBIOS flags in the packet headers.
-M|--master-browser Search for a local master browser by looking up netbios_name<1d>. If netbios_name is specified as a dash (-), a lookup is done on the special name _ _ MSBROWSE_ _.
-R|--recursion Set the "recursion desired" bit in the packet. This causes the system that responds to try a WINS lookup and return the address and any other information the WINS server has saved.
-r|--root-port Use the root port of 137. This option exists as a bug workaround for Windows 95. This option might require the user to be superuser.
-S|--status Perform a node status query once the name query has returned an IP address. This returns all the resource types that the system knows about, including their numeric attributes.
-T|--translate Translate IP addresses into resolved names.
-U|--unicast unicast_address Perform a unicast query to the specified address. Used with -R to query WINS servers.
The ntlm_auth tool similar to a command-line version of the pam_winbind library and is provided for Unix daemons that require support for the NTLM challenge/response authentication. The most popular use of a ntlm_auth is in combination with the Squid Web Proxy server, although the tool has also been used in conjunction with PPP services, Apache authentication modules, and RADIUS servers, to name a few examples.
Command synopsis -
ntlm_auth [options]
The ntlm_auth commands supports the general option set used by many Samba client tools and discussed earlier in this appendix.
Options -
--challenge hex_string The NTLMSSP challenge, as a hexadecimal-encoded string.
--diagnostics Print additional information in order to help debug failures in the authentication process.
--domain name The user's domain name to use during authentication.
--helper-protocol protocol_version Use the standard input helper protocol_version. The list of currently valid protocol names is: - gss-spnego
- gss-spnego-client
- ntlm-server-1
- ntlmssp-client-1
- squid-2.4-basic
- squid-2.5-basic
- squid-2.5-ntlmssp
--lm-response hex_string The LanManager response string as a hexadecimal encoded string.
--nt-response hex_string The NT response string, as a hexadecimal encoded string.
--password passphrase The user's clear-text password to use in the authentication request.
--request-lm-key Request that the LanManager session key be displayed on standard output.
--request-nt-key Request that the NT session key be displayed on standard output.
--require-membership-of SID Verify that the user is a member of the domain group specified by the SID.
--username name The user's login name to use in the authentication request.
--workstation name The user's workstation name to use in the authentication request.
This program can be used to manage accounts that are held in a passdb module. Because this tool uses the passdb storage mechanisms directly and not MS-RPC, you must be the superuser to operate this tool.
Command synopsis -
pdbedit [options] username
The pdbedit utility supports the general option set common to many Samba client tools.
Options -
-a|--create Add the username to the SAM database. The command issues a prompt for the user's password.
-b|--backend pwdb_name Specifiy the passdb backend name to use for the current operation, in place of the value define in smb.conf.
-C|--value integer The value of an account policy. Refer to the --account-policy option for details on available policy names.
-c|--account-control flags Define the account control flags for a user. The flags value must be a collection of one or more of the following types: N, D, H, L, or X. The account control flags must be enclosed using square brackets ([]). Discussions regarding the meaning of flags can be found in Chapter 5.
-D|--drive drive_letter Set the Windows drive letter to which to map the user's home directory. The drive letter should be specified as a letter followed by a colone.g., H:.
-e|--export pwdb_backend Export the user account database to another passdb format, written to the specified location. Used for migrating from one type of account database to another. The pwdb_backend argument is specified in the format of a valid passdb backend name, followed by a colon, then the location of the database. For example, to export the existing account database to an smbpasswd database in the file /etc/samba/smbpw, pwdb_backend would be specified as smbpasswd:/etc/samba/smbpw.
-f|--fullname full_name Set the full name of the user specified with the -u option.
-h|--homedir unc Set the home directory path (as a UNC) for the user specified with the -u option.
-I|--domain name Set the user's domain.
-i|--import pwdb_backend A password database backend from which to retrieve account information, overriding the one specified by the passdb backend parameter in the Samba configuration file. This, along with the --export option, is useful for migrating user accounts from one type of account database to another. See the --export option regarding how to specify the pwdb_backend argument.
-L|--list List the user accounts in the database. See also the --verbose option.
-m|--machine Indicate that the account is a computer account rather than a user account. Used only with the -a option when creating the account.
-N|--account-desc string Set the user's account description string.
-P|--account-policy policy_name Define the policy to be modified by the --value parameter. Because the policy names contain whitespace, be sure to enclose the string in quotes. Valid policy names are as follows: - bad lockout attempt
- disconnect time
- lockout duration
- maximum password age
- min password length
- minimum password age
- password history
- refuse machine password change
- reset count minutes
- user must logon to change password
-p|--profile UNC_path Set the directory in which the user's profile is kept. The directory is specified as a UNC.
-r|--modify Update an existing user rather than creating a new user.
-S|--script UNC_path The UNC of the user's logon script.
-t|--password-from-stdin passphrase Sets the user's password from standard input rather than prompting.
-U|--user-sid SID Explicitly define the user's SID.
-u|--user username The username of the account to add (with the -a option), delete (with the -x option), or modify.
-v|--verbose Use verbose mode when listing accounts with the --list option. The account fields will be printed.
-w|--smbpasswd-style Use the smbpasswd listing mode, for use with the --list option, which prints information in the same format as it would appear in an smbpasswd file.
-x|--delete Delete the user (specified with the -u option) from the account database.
-Z|--logon-hours-reset Reset a user's login hours acccount restrictions.
-z|--bad-password-count-reset Reset a user's bad password count to 0. Frequently, you will need to unlock the account as well, unless the time specified by the "lockout duration" policy has elapsed.
The profiles program is a small utility for changing the SID in registry ACLs such as those found in user roaming profiles (NTUSER.DAT). This is useful when migrating user profiles from one domain to another.
Command synopsis -
profiles [options] filename
The profiles command supports the general option set common to many Samba client tools.
Options -
-c|--change-sid SID The original SID that should be modified in access control entries.
-n|--new-sid SID The new SID that should replace any occurrences of the --change-sid value.
This program provides a way of remotely modifying Windows ACLs on files and directories stored on an SMB/CIFS share.
Command synopsis -
smbcacls //server/share filename [options]
The smbcacls tool supports the standard general and authentication options described earlier in this appendix.
Options -
-a|--add ACLs Add one or more ACLs to the file or directory. Any ACLs already existing for the file or directory are unchanged.
-C|--chown username Change the owner of the file or directory. This is a shortcut for -M OWNER:username. The username argument can be given as a username or as the string format of a SID.
-D|--delete ACLS Delete the specified ACLs.
-G groupname Change the group of the file or directory. This is a shortcut for -M GROUP:groupname. The groupname argument can be given as a group name or as the string format of a SID.
-M acls Modify the mask of the ACLs specified. Refer to the following section, "Specifying ACLs" for details.
--numeric Don't resolve SIDs or access masks to their corresponding string representations.
-S|--set ACLS Set the specified ACLs, deleting any ACLs previously set on the file or directory. The ACLs must contain at least a revision, type, owner, and group.
-t|--test-args Validate the command-line arguments, but do not actually perform the requested modifications.
Specifying ACLs In the previous options, the same format is always used when specifying ACLs. An ACL is made up of one or more Access Control Entries (ACEs), separated by either commas or escaped newlines. An ACE can be one of the following: - REVISION:revision_number
- OWNER:username_or_SID
- GROUP:group_name_or_SID
- ACL:name_or_SID:type/flags/mask
The revision_number should always be 1. The OWNER and GROUP entries can be used to set the owner and group for the file or directory. The names can be the textual ones or the string representation of the SIDs. The ACL entry specifies what access rights to apply to the file or directory. The name_or_SID field specifies to which user or group the permissions apply and can be supplied either as a textual name or a SID. An ACE can be used to either allow or deny access. The type field is set to 1 to specify a permission to be allowed or 0 for specifying a permission to deny. The mask field is the name of the permission and is one of the following:
R Read access.
W Write access.
X Execute permission.
D Permission to delete.
P Change permissions on the object.
O Take ownership. The following combined permissions can also be specified:
READ Equivalent to RX permissions
CHANGE Equivalent to RWXD permissions
FULL Equivalent to RWXDPO permissions The flags field is for specifying how objects in directories are to inherit their default permissions from their parent directory. For files, flags is normally set to 0. For directories, flags is usually set to either 9 or 2.
The smbclient program is the "Swiss Army knife" of the Samba suite. Initially developed as a testing tool, it has become a command shell capable of acting as a general-purpose Unix client, with a command set very similar to that of ftp. It offers the following set of functions: Interactive file transfer, similar to ftp Interactive printing to shared SMB printers Interactive tar format archiving Sending messages on the SMB network Batch mode tar format archiving Enumerating shares and workgroup contents on remote servers Debugging
Command synopsis -
smbclient //server/share [password] [options]
It is possible to run smbclient noninteractively, for use in scripts, by specifying the -c option along with a list of commands to execute. Otherwise, smbclient runs in interactive mode, prompting for commands like this: smb:\>
The backslash in the prompt is replaced by the current directory within the share as you change your working directory with smbclient's cd command. The smbclient command supports all three sets of command-line options (general, authentication, and connection) common to other Samba client tools.
Options -
-b|--send-buffer buffer_size The size of the buffer used when transferring files. It defaults to 65,520 bytes and can be changed as a tuning measure. Generally, it should be quite large or set to match the size of the buffer on the remote system.
-c|--command command_string Pass a command string to the smbclient command interpreter. The argument consists of a semicolon-separated list of commands to be executed.
-D|--directory init_dir Upon starting up, causes smbclient to change its working directory to init_dir on the remote host.
-E|--stderr Send output from commands to stderr instead of stdout.
-g|--grepable When used in conjuction with the -L option, this parameter instructs smbclient to display share, server, and workgroup lists in a format that is easily parseable in shell scripts.
-I|--ip-address IP_address Set the IP address of the server to which the client connects.
-L|--list server List services (shares) offered by the server. This can be used as a quick way to test an SMB/CIFS server to see if it is working. If there is a name-service problem, use the -I option to specify the server.
-M|--message NetBIOS_name Allows you to send messages using the Windows messaging protocol. Once a connection is established, you can type your message, pressing Ctrl-D to end. The -U and -I options can be used to control the "From" and "To" parts of the message.
-m|--max-protocol level The maximum SMB/CIFS protocol dialoect that smbclient will advertise when negotiating a connection with a remote server. Valid protocol names are: - NT1
- LANMAN2
- LANMAN1
- CORE
- COREPLUS
-p|--port port_number The port number used by smbclient to connect to the server.
-R|--name-resolve resolve_order Set the resolve order of the name servers. This option is similar to the resolve order configuration option and can take any of the four parameters lmhosts, host, wins, and bcast, in any order. If more than one parameter is specified, the argument is specified as a space-separated list. This option can be used to test name service by specifying only the name service to be tested.
-T|--tar command_string tarfile Run the tar archiver, which is gtar compatible. The tar file that is written to or read from is specified by tarfile. The two main commands are c (create) and x (extract), which can be followed by any of these options:
a Reset the archive attribute on files after they have been saved. See also the g option.
b size The block size for writing the tar file, in 512-byte units.
g Back up only files that have their archive bit set. See also the a option.
I filename Includes files and directories. This is the default behavior, so specifying this is redundant. To perform pattern matching, see also the r option.
N filename Back up only those files newer than filename.
q Suppress diagnostics.
r Perform regular expression matching, which can be used along with the I or X option to include or exclude files.
X filename Exclude specified files and directories.
Commands -
?|help [ smbclient_command With no command specified, print a list of available commands. If a command is specified as an argument, a brief help message will be printed for it.
! shell_command Shell escape. Run the specified command in a Unix shell.
altname filename Cause smbclient to request from the server and then print the old-style, 8.3-format filename for the specified file.
archive level This controls the behavior in relation to the DOS archive bit when retrieving files. The available levels are:
0 Ignore the archive bit entirely.
1 Retrieve only files whose archive bit is set.
2 Same as level 1 but resets the archive bit after the file copy.
3 Same as level 0 but resets the archive bit after the file copy.
blocksize The blocksize to be used when writing tar files. The value must be between 0 and 65535.
cancel print_jobid [...] Cause smbclient to request the server to cancel one or more print jobs, as specified by the numeric job IDs provided as arguments. See also the queue command, which prints job ids.
case_sensitive Allows you to toggle case-sensitive and -insensitive filename lookups. The default is to match Windows behavior and use case-insensitive lookups.
cd [ directory] With no argument, print the current working directory on the remote system. If a directory name is supplied as an argument, change the working directory on the remote system to that specified.
chmod filename octal_mode Requests that the server change the Unix file permissions on filename to octal_mode, specified in octal numeric format. Works only if the server supports CIFS Unix extensions.
chown filename UID GID Change the owner and group of the file specified by filename to those provided as decimal numeric arguments uid and gid. Works only if the server supports CIFS Unix extensions.
del filename Delete one or more files, as specified by the argument, from the current working directory. The argument can be a filename globbing pattern using the * and ? characters.
dir [ filename] With no arguments, print a list of files and directories in the working directory on the server. If an argument is provided, only files and directories whose names match the argument will be listed. The argument can be a filename globbing pattern using the * and ? characters.
du Calculate the disk usage and free space available for the share.
exit Quit the smbclient program after terminating the SMB connection to the server. The q and quit commands are aliases for exit.
get remote_file [ local_file] Copy the file specified by remote_file from the server to the local system. If no local_file argument is specified, smbclient will name the local file the same as it is named on the server. If local_file is specified, it will be used as the name of the local copy. See also the lowercase command.
getfacl filename Display the POSIX ACL for filename. This operation is supported only if the remote server supports the CIFS Unix Extensions.
hardlink source destination A Windows hardlink from destination to source. Refer to the link command for creating Unix hard links.
history Display a list of recently executed smbclient commands.
lcd [ directory] If no argument is provided, print the name of smbclient's working directory on the local system. If a directory name is provided as an argument, changes smbclient's working directory to the directory specified.
link link_name filename Create a hard link to filename and name it link_name. This command works only if the server supports CIFS Unix extensions.
listconnect Display all current SMB/CIFS connections held by the current smbclient session. This is really only of interest when connecting to MS-DFS root shares and following referrals.
lowercase Toggle the Boolean lowercasing setting. When this setting is on, names of files copied from the server with the get and mget commands will be changed to all lowercase. This is mainly used for accessing servers that report filenames in all uppercase only.
mask [ globbing_pattern] Set the filename globbing pattern for use with the mget and mput commands when recursion is turned on. (When recursion is off, the setting has no effect.) Both mget and mput accept a globbing pattern as arguments; however, those patterns apply only to the current directory. This command specifies the pattern used for all subdirectories that are recursively traversed. The pattern stays in effect until it is changed with another mask command. To return the setting to its original default, specify a globbing_pattern of an asterisk (*), which matches all files. See also the mget, mput, and recurse commands.
mget pattern When recursion is turned off, copy files matching the file-globbing pattern, as specified by the argument, from the current working directory on the server to the local system. When recursion is on, the pattern argument is used to match directories in the current working directory, and the pattern specified by the mask command is used for matching files within each directory and all subdirectories. See also the lowercase, mask, and recurse commands.
mkdir Create a directory on the remote share.
more View a remote file using the local system's configured pager tool (e.g., the more command).
mput pattern When recursion is turned off, copy files matching the file-globbing pattern, as specified by the argument, from the current working directory on local system to the remote server. When recursion is on, the pattern argument is used to match directories in the current working directory, and the pattern specified by the mask command is used for matching files within each directory and all subdirectories. See also the lowercase, mask, and recurse commands.
newer filename Retrieve files with a timestamp newer than the one assigned to filename.
print filename Print the specified file. This command requires that smbclient be connected to a print share.
prompt Toggle the prompting mode. When prompting is on (the default), the mget and mput commands will interactively prompt the user for permission to transfer each file. The user can answer either y (yes) or n (no), followed by a newline, to this prompt. When prompting is off, all the files will be transferred with no prompts issued.
put local_file [ remote_file] Copy the file specified by local_file from the local to the remote system. If no remote_file argument is specified, smbclient will name the remote file the same as it is named on the local system. If remote_file is specified, it will be used as the name of the remote copy. See also the lowercase command.
pwd Print the current working directory on the server.
queue Print information on the print queue on the server. This command requires that smbclient is connected to a print share.
recurse Toggle the recursion mode, which affects the mget and mput commands. When recursion is off (the default), the mget and mput commands will copy only files from the current working directory that match the file-globbing pattern specified as an argument to the command, and the pattern set by the mask command is ignored. When recursion is turned on, the mget and mput commands recursively traverse any directories that match the pattern specified as the argument to the command, and the pattern set by the mask command is used to match files in those directories.
rename source destination Rename the source file (or directory) to destination.
reput filename [ remote_filename] Append a file from the local server to filename (or remote_filename if specified) on the remote server.
rmdir directory Requests that the server remove the specified directory.
setmode filename attributes Assign the specified MS-DOS file attributes on the specified file. The attributes argument has the format of a leading plus sign (+) or minus sign (-) either to set or to unset the attribute(s), respectively, followed by one or more of the characters r (read), s (system), h (hidden), or a (archive).
showconnect Display the active connenction for the current working directory. This command allows you to determine what server you are connected to after following a MS-DFS referral.
stat filename Perform a Unix stat( ) call on the remote filename. This call requires that the server support the CIFS Unix Extensions.
symlink link_name filename Request that the server create a symbolic link named link_name to filename. This command works only if the server supports Unix CIFS extensions. The server will not create a link that refers to a file not in the share to which smbclient is connected.
tar cmd_str Perform an archiving operation using the tar format. This is the interactive form of the -T command-line operation, and the cmd_str argument is specified in the same manner. See also the tarmode command.
blocksize size The block size, in units of 512 bytes, for files written by the tar command.
tarmode mode ... Specify how the tar command performs its archiving, including how it handles the archive attribute on files. Multiple mode arguments can be provided:
full All files will be included, regardless of whether their archive attribute is set. This is the default behavior.
inc Only files that have the archive attribute set will be included in the backup.
reset The archive attribute will be unset by tar after the file is included in the archive.
noreset The archive attribute will be left unchanged. This is the default.
hidden|nohidden Controls whether files with the hidden attribute set will be included in the archive. The default is to include files with the hidden bit set.
system|nosystem Determines whether files with the system attribute set will be included in the archive. The default is to include files with the system bit set.
verbose|noverbose If verbose mode is enabled (the default), file names will be printed as each one is included in the archive (when creating the archive) or is read from the archive (when extracting it).
volume Display the volume name of the share containing the current working directory. The volume name is dependent on the current connect when following MS-DFS referrals. Also refer to the showconnect command.
The smbcontrol command sends control messages to running smbd, nmbd, or winbindd processes.
Command synopsis -
smbcontrol [options] process message-type [parameters]
smbcontrol supports the standard --version , --help, and the --configfile options described in the previous General Options section.
Options -
-t|--timeout seconds The period before timing out while waiting for a response to a message. Each smbcontrol command has up to three parts:
process The process or group of processes to which to send the message. If process is smbd or winbindd, all named processes will receive the message. If process is nmbd, only the main nmbd process (identified by Samba's nmbd.pid file) receives the message. If process is the numeric PID of a running process on the system, that process will receive the message.
message-type The type of message that is sent. For more information, see the section "smbcontrol message types" that follows.
parameters Additional parameters required by some messages.
smbcontrol message types -
close-share share_name Close the connection to a share or shares. If share_name is specified as an asterisk (*), connections to all shares will be closed. To close a single connection, share_name is given as the name of a share, as specified in the Samba configuration file, not including the enclosing brackets. No message is printed if there is an error in specifying share_name.
debug num The debugging level. The num parameter specifies the level, which can be from 0 to 10.
debuglevel Print the current debugging level.
dmalloc-mark Instruct a process to remember a memory watermark. This option is of use only when the --enable-dmalloc option was included during the initial compilation.
dmalloc-log-changed Display the memory allocation statistics since the last dmalloc-mark command. This option is of use only when the --enable-dmalloc option was included during the initial compilation.
drvupgrade driver_name Send a notify message to smbd that driver_name has been changed so that the daemon can rebind driver initialization data to associated printers.
force-election Can be used only with nmbd, telling it to force a master browser election.
nodestatus Ask the nmbd daemon to perform a NetBIOS node status request.
ping number Sends number of pings and reports when they receive a reply or timeout. Used for connectivity testing.
profile mode This command controls profiling statistics collection. If mode is on, profile statistics will be collected. If mode is off, collection of statistics is turned off. If mode is specified as count, only counting statistics are collected (and not timing statistics). If mode is flush, the data set is cleared (initialized).
profilelevel Print the current profiling level.
pool-usage Dump the statistics for all current talloc( ) memory allocation.
printer-notify printer_name Send a notify message to smbd that printer_name has been changed so that the daemon can send a notification to any cliented monitoring that printer.
reload-config Instruct a daemon to reload its configuration information. This is an alternative to sending a process the HUP signal.
shutdown Ask a running process to gracefully terminate.
The smbcquotas program provides a simple interface to query and set filesystem quotas on remote SMB/CIFS shares.
Command synopsis -
smbcquotas //server/share [options]
The smbcquotas tool supports the standard general and authentication options described earlier in this appendix.
Options -
-F|--fs Display filesystem quotas configured on the share.
-L|--list Display all user quotas configured on the share.
-n|--numeric Don't resolve SIDs or access masks to their corresponding string representations.
-S|--set quota_string Set the quota_string value for the SMB/CIFS share. The format of quota_string is covered in the Quota Settings section.
-t|--test-args Validate the command-line arguments but do not actually perform the requested modifications.
-u|--user username Display the quota settings for username.
-v|--verbose Increase the amount of information messages written to standard output.
Quota settings Quota strings passed to the --set parameter can be in one of three forms. The first form is used to set a user quota policy. The username refers to the user whose quota is being set or modified. The softlimit and hardlimit values are given in bytes. UQLIM:username/softlimit/hardlimit
The second type of quota string controls the filesystem quota setings. Once again the softlimit and hardlimit values are given in bytes. FSQLIM:softlimit/hardlimit
The final format of the quota string defines overall quota behavior. FSQFLAGS:flags
The flags argument is one of more of the following values, using the forward slash character (/) to delimit entries: - QUOTA_ENABLED
- DENY_DISK
- LOG_SOFTLIMIT
- LOG_HARD_LIMIT
The smbpasswd program provides the general function of managing encrypted passwords. How it works depends on whether it is run by the superuser or an ordinary user. For the superuser, smbpasswd can be used to maintain Samba's passdb backend. It can add or delete users, change their passwords, and modify other attributes pertaining to the users that are held in (for example) an smbpasswd file, the tdbsam database, or an LDAP directory service using ldapsam. When run by ordinary users, smbpasswd can be used only to update their encrypted passwords using the SMB/CIFS password change mechanisms. In this mode of operation, smbpasswd acts as a client to the Samba or Windows server.
Command synopsis When run by the superuser: smbpasswd [options] username
In this case, the username of the user whose passdb entry is to be modified is provided as the second argument. Otherwise: smbpasswd [options]
The smbpasswd command does not support any of the common Samba command-line parameters in order to ensure better backwards compatibility with older Samba releases.
Superuser-only options -
-a username Add a user to the encrypted password file. The user must already exist in the system password file (/etc/passwd). If the user already exists in the passdb backend, the -a option changes the existing password.
-d username Disable a user in Samba's list of accounts. The user's entry in the file will remain, but will be marked with a flag disabling the user from authenticating.
-e username Enable a disabled user in the encrypted password file. This option overrides the effect of the -d option.
-m This option indicates that the account is a computer account rather than a user account. This older method of creating machine trust accounts in a Samba domain is strongly discouraged. Alternative methods of joining clients to a Samba domain are covered in Chapter 9.
-n Set the user's password to a null password. For the user to authenticate, the parameter null passwords = yes must exist in the [global] section of the Samba configuration file.
-R resolve_order_list Set the resolve order of the name servers. This option is similar to the resolve order configuration option and can take any of the four parameters lmhosts, host, wins, and bcast, in any order. If more than one parameter is specified, the argument is specified as a space-separated list.
-w password The password that goes with the value of the ldap admin dn Samba configuration file parameter.
-W Same as -w, but prompts for the password rather than reading it in as a command-line parameter.
-x username Delete the user from Samba's list of user accounts. This is a one-way operation, and all information associated with the entry is lost. To disable the account without deleting the user's entry in the file, see the -d option.
Other options -
-c filename Specifies the Samba configuration file, overriding the compiled default.
-D debug_level The debug (also called logging) level. The level can range from 0 to 10. Debug level 0 logs only the most important messages; level 1 is normal; levels 3 and above are primarily for debugging and slow the program considerably.
-h Print command-line usage information.
-r NetBIOS_name Specify on which machine the password should change. If changing a Windows (or Samba) domain password, the remote system specified by NetBIOS_name must be the PDC for the domain. The user's username on the local system is used by default. See also the -U option for use when the user's Samba username is different from the local username.
-s Cause smbpasswd not to prompt for passwords, but instead to read the old and new passwords from the standard input. This is useful when calling smbpasswd from a script.
-U username Change the password for username on the remote system. This is to handle instances in which the remote username and local username are different. This option requires that -r also be used.
The smbget command is an SMB/CIFS variant of the Unix wget command. The tool is similar to smbclient's get (or mget) command but makes use of the SMB URI syntax instead of UNC paths. Multiple file locations can be specified to be retrieved sequentially.
Command synopsis -
smbget [options] SMB_URI [SMB_URI . . .]
Options -
-a|--guest Use an anonymous connection.
-b|--blocksize size Define the blocksize to be size bytes for SMB/CIFS file transfers.
-D|--dots Display progress dots during the file download.
-d|--debuglevel level The verbosity of log messages to write to the console.
-f|--rcfile filename Parse smbget options from the resource file filename.
-n|--nonprompt Do not prompt for user interaction when downloading files or overwriting local files.
-O|--stdout Write the retreived file to standard output.
-o|--outputfile filename Write the retreived file to filename.
-P|--keep-permissions Ensure that the local file has the same permission set as the original copy on the remote server.
-p|--password passphrase Specify the password to send in the authentication request.
-q|--quiet Write only minimal information messages during file downloads.
-R|--recursive When the SMB_URI specifies a directory, recursively download files from the directory tree.
-r|--resume Resume an incomplete file transfer.
-u|--username name The login name to send in the authentication request.
-w|--workgroup name The domain name to send in the authentication request.
-v|--verbose Generate extra output to trace connection operations.
The smbspool program provides the SMB/CIFS backend interface to the Common Unix Printing System. Although smbspool can be made to work with non-CUPS printing systems, it is recommend that you use smbclient instead in these environments.
Command synopsis -
smbspool [DEVICE_URI] job-id user title copies options [filename]
The arguments for smbspool, as shown here, are those used in the CUPS printing system. The printer that the job is to be sent to is specified in the SMB URI format as the first argument or in the DEVICE_URI environment variable. The job argument refers to the job number. The user argument is the name of the user who submitted the print job. The title argument is the name of the print job and must be supplied. It is used as the name of the remote print file. The copies argument is the number of copies that will be printed. This number is used only if the (optional) filename argument is supplied. Otherwise, only one copy is printed. The options argument, for specifying printing options, is ignored. The filename argument is used for specifying the name of the file to be printed. If it is not provided, the standard input will be used.
This program lists the current connections on a Samba server.
Command synopsis -
smbstatus [options]
The smbstatus tool supports the set of general command-line options previously described in this appendix.
Options -
-B|--byterange Produce information about byte range locks only.
-b|--brief Cause smbstatus to produce brief output. This includes the version of Samba and auditing information about the users that are connected to the server.
-L|--locks Print only the list of current file locks.
-n|--numeric Do not convert Unix uids and gids to their associated names.
-p|--processes Print only a list of smbd process IDs.
-S|--shares Print only a list of shares and their connections.
-u|--user username Limit the report to the activity of a single user.
-v|--verbose Include additional information about current connections, locks, and processes.
The smbtar program is a shell-script wrapper around smbclient for doing tar-format archiving operations. It is functionally very similar to the Unix tar program.
Command synopsis -
smbtar [options] [include|exclude filenames]
Options -
-a Reset (clears) the archive attribute on files after they are backed up. The default is to leave the archive attribute unchanged.
-b blocksize The block size, in units of 512 bytes, for reading or writing the archive file. Defaults to 20, which results in a block size of 10,240 bytes.
-d directory Changes the working directory on the remote system to directory before starting the restore or backup operation.
-i Specify incremental mode; files are backed up only if they have the DOS archive attribute set. The archive attribute is reset (cleared) after each file is read. The default behavior is to ignore the archive bit and perform a full backup
-l log_level The logging level. This corresponds to the --debuglevel option of smbclient and other Samba programs.
-N filename Backs up only files newer than filename. For incremental backups.
-p password The password to use to access a share. An alternative to using the username%password format with the -u option.
-r Restore files to the share from the tar file.
-s server The SMB server. See also the -x option.
-t filename The file or Unix device to use as the archiving medium. The default is tar.out or the value of the TAPE environment variable, if it has been set.
-u username The user account to use when connecting to the share. You can specify the password as well, in the format username%password. The username defaults to the user's Unix username.
-v Operate in verbose mode, printing error messages and additional information that can be used in debugging and monitoring. Backup and restore operations will list each file as it is processed.
-x share The name of the share on the server to which to connect. The default is backup. See also the -s option.
-X file_list Exclude the specified files from the backup or restore operation.
The smbtree program is similar to the findsmb Perl script, in that it enumerates workgroup contents. However, smbtree groups servers by workgroup and can includes a list of available shares on each server.
Command synopsis -
smbtree [options]
The smbtree command supports the general and authentication option sets common to many Samba client tools.
Options -
-b|--broadcast Broadcast requests for workgroup contents rather than attempting to query the master browser.
-D|--domains Only enumerate workgroups names.
-S|--servers Do not enumerate shares on servers. List only the workgroup names and the servers contained in each workgroup.
The tdbbackup program validates a tdb file and creates a backup copy of the original database. This tool can be use to create backup copies while Samba is running. The structure-generated tdb file is guaranteed to be consistent, but if a Samba daemon possessed data cached in memory, the original tdb file itself may have been in a inconsistent state. Therefore, it is best to perform backups when the server is under a light load.
Command synopsis -
tdbbackup [options] filename.tdb
Options -
-h Display a brief help listing.
-s suffix Specify the suffix to append to backup files.
-v Validate a tdb file. If file corruption is detected, you must restore it from a valid backup copy.
The tdbdump tool prints the contexts of a tdb file to standard output.
Command synopsis -
tdbdump filename.tdb
The tdbtool program is an interactive utility for viewing and modifying tdb files. It should be viewed as a very low-level database management tool and used only as a last resort.
Command synopsis -
tdbtool filename.TDb
After opening filename.tdb, you will be presented with a basic TDb> prompt. You can view the list of available commands by running the help command.
tdbtool commands -
create dbname Create a new tdb file named dbname.
cdump Dump the tdb contents as a series of connection records.
delete key Remove a record from the tdb.
dump Dump the tdb contents as strings.
erase Remove all records in the current open tdb file.
freelist Display the database internal freelist structure.
hexkeys Dump the database keys as hexadecimal strings.
info Print summary information about the tdb structure and records.
insert key data Add a new record to the tdb.
keys Dump the database keys as ASCII strings.
list Display the database's internal hashlist and freelist structures.
move key newfilename.tdb Move a record referenced by key in the current open tdb to newfilename.tdb.
open dbname Open an existing tdb filename dbname.
show key Display the record indexed by key.
store key data Replace an existing record in the tdb.
quit Exit the current tdbtool interactive session.
The testparm program checks a Samba configuration file for obvious errors.
Command synopsis -
testparm [options] [filename] [hostname] [IP_addr]
If the configuration file is not provided using the filename argument, then it defaults to the compile time location (e.g., /usr/local/samba/lib/smb.conf). If the hostname and an IP address of a system are included, an extra check is made to ensure that the system is allowed to connect to each service defined in the configuration file. This is done by comparing the hostname and IP address to the definitions of the hosts allow and hosts deny parameters. In addition to the following options, testparm also supports the standard --help, --usage, and --version arguments.
Options -
-L|--server server_name Set the %L configuration variable to the specified server name.
--parameter-name parameter_name Print only the value of parameter_name to standard output.
-s|--suppress-prompt Disable the default behavior of prompting for the Enter key to be pressed before printing the list of configuration options for the server.
--section-name share Limit the parameter listing to the smb.conf section share.
--show-all-parameters Display a listing of all parameter names, type, and possible values. The output is formatted so that it can easily be parsed in shell scripts.
-t|--encoding encoding_name Print the smb.conf parameters and values using the specified character encoding_name.
-v|--verbose Enable verbose output that includes listing all smb.conf parameters, even if set to the default value. The default behavior is to provide a brief listing on only nondefault settings.
This program retrieves and prints information from the winbindd daemon, which must be running for wbinfo to function.
Command synopsis -
wbinfo [options] [--domain=name]
Some command-line parameters allow you to limit the request to a specific domain defined by the --domain argument. In addition to the following options, wbinfo also supports the standard --help, --usage, and --version arguments.
Options -
-A|--allocate-rid Allocate a new RID from the passdb backend and print the assigned value.
-a|--authenticate username% password Check to see whether a user can authenticate through winbindd using the specified username and password. Any user may request the clear text authentication, but only the root user is able to test the challenge/response authentication mechanism.
-D|--domain-info DOMAIN Print information about the specified DOMAIN such as the domain SID, status of AD services, and realm name, if available.
-G|--gid-to-sid gid Convert the Unix gid to a Windows SID.
-g|--domain-groups Prints all groups that exist in Winbind's own domain as well as any trusted domains.
--getdcname DOMAIN Query a domain controller in Winbind's own domain for the name of a valid DC in the trusted DOMAIN.
--get-auth-user Print the currently defined auth-user, if one has been specified using the --set-auth-user option.
-I|--WINS-by-ip ip_address Send a request to the WINS server configured in smb.conf to convert the ip_address to a NetBIOS name.
-m|--trusted-domains List all trusted domains known by winbindd included in the BUILTIN and local machine domains.
-N|--WINS-by-name name Send a request to the WINS server configured in smb.conf to convert the name to an IP address.
-n|--name-to-sid name Print the SID corresponding to the name specified. The argument can be specified as DOMAIN/name (or by using a character other than the slash, as defined by the Winbind separator character) to specify both the domain and the name. If the domain and separator are omitted, the value of the workgroup parameter in the Samba configuration file is used as the name of the domain.
-p|--ping Send a simple ping request to winbindd to determine whether it is running.
-r|--user-groups username Print the list of Unix group IDs to which the domain user belongs.
-S|--sid-to-uid SID Convert the SID to a Unix uid and prints the result.
-s|--sid-to-name SID Convert the specified SID to a user or group name.
--separator Print the current winbind separator character.
--set-auth-user username% password An alternative set of credentials to use when connecting to a domain controller. This option is normally not needed in current Samba releases.
--sequence Print the current known sequence numbers for all trusted domains. This can be helpful in debugging problems since unavailable domains will be listed as DISCONNECTED.
-t|--check-secret Request winbindd to validate the Samba's current machine trust account.
-U|--uid-to-sid uid Convert the Unix uid to a Windows SID.
-u|--domain-users Print all users that exist in Winbind's own domain, as well as any trusted domains.
--user-domgroups SID List the SIDs of all domain groups to which the user belongs.
--user-sids SID Retrieve a list of SIDs for all groups to which the user belongs, including domain local groups. |
