Samba3-HOWTO/TOSHARG-TheNetCommand.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3
   4 <chapter id="NetCommand">
   5 <chapterinfo>
   6         &author.jht;
   7         &author.vl;
   8         &author.gd;
   9         <pubdate>May 9, 2005</pubdate>
  10 </chapterinfo>
  11
  12 <title>Remote and Local Management: The Net Command</title>
  13
  14 <para>
  15 <indexterm><primary>net</primary></indexterm>
  16 <indexterm><primary>remote management</primary></indexterm>
  17 <indexterm><primary>command-line</primary></indexterm>
  18 <indexterm><primary>scripted control</primary></indexterm>
  19 The <command>net</command> command is one of the new features of Samba-3 and is an attempt to provide a useful
  20 tool for the majority of remote management operations necessary for common tasks. The <command>net</command>
  21 tool is flexible by design and is intended for command-line use as well as for scripted control application.
  22 </para>
  23
  24 <para>
  25 <indexterm><primary>net</primary></indexterm>
  26 <indexterm><primary>network administrator's toolbox</primary></indexterm>
  27 <indexterm><primary>smbgroupedit</primary></indexterm>
  28 <indexterm><primary>rpcclient</primary></indexterm>
  29 Originally introduced with the intent to mimic the Microsoft Windows command that has the same name, the
  30 <command>net</command> command has morphed into a very powerful instrument that has become an essential part
  31 of the Samba network administrator's toolbox. The Samba Team has introduced tools, such as
  32 <command>smbgroupedit</command> and <command>rpcclient</command>, from which really useful capabilities have
  33 been integrated into the <command>net</command>. The <command>smbgroupedit</command> command was absorbed
  34 entirely into the <command>net</command>, while only some features of the <command>rpcclient</command> command
  35 have been ported to it. Anyone who finds older references to these utilities and to the functionality they
  36 provided should look at the <command>net</command> command before searching elsewhere.
  37 </para>
  38
  39 <para>
  40 A Samba-3 administrator cannot afford to gloss over this chapter because to do so will almost certainly cause
  41 the infliction of self-induced pain, agony, and desperation. Be warned: this is an important chapter.
  42 </para>
  43
  44         <sect1>
  45         <title>Overview</title>
  46
  47         <para>
  48 <indexterm><primary>standalone</primary></indexterm>
  49 <indexterm><primary>domain member</primary></indexterm>
  50 <indexterm><primary>PDC</primary></indexterm>
  51 <indexterm><primary>BDC</primary></indexterm>
  52 <indexterm><primary>DMS</primary></indexterm>
  53 <indexterm><primary>authentication</primary></indexterm>
  54         The tasks that follow the installation of a Samba-3 server, whether standalone or domain member, of a
  55         domain controller (PDC or BDC) begins with the need to create administrative rights. Of course, the
  56         creation of user and group accounts is essential for both a standalone server and a PDC.
  57         In the case of a BDC or a Domain Member server (DMS), domain user and group accounts are obtained from
  58         the central domain authentication backend.
  59         </para>
  60
  61         <para>
  62 <indexterm><primary>server type</primary></indexterm>
  63 <indexterm><primary>local UNIX groups</primary></indexterm>
  64 <indexterm><primary>mapped</primary></indexterm>
  65 <indexterm><primary>domain global group</primary></indexterm>
  66 <indexterm><primary>UID</primary></indexterm>
  67 <indexterm><primary>GID</primary></indexterm>
  68 <indexterm><primary>access rights</primary></indexterm>
  69 <indexterm><primary>net</primary></indexterm>
  70         Regardless of the type of server being installed, local UNIX groups must be mapped to the Windows
  71         networking domain global group accounts. Do you ask why? Because Samba always limits its access to
  72         the resources of the host server by way of traditional UNIX UID and GID controls. This means that local
  73         groups must be mapped to domain global groups so that domain users who are members of the domain
  74         global groups can be given access rights based on UIDs and GIDs local to the server that is hosting
  75         Samba. Such mappings are implemented using the <command>net</command> command.
  76         </para>
  77
  78         <para>
  79 <indexterm><primary>PDC</primary></indexterm>
  80 <indexterm><primary>BDC</primary></indexterm>
  81 <indexterm><primary>DMS</primary></indexterm>
  82 <indexterm><primary>security account</primary></indexterm>
  83 <indexterm><primary>domain authentication</primary></indexterm>
  84 <indexterm><primary>trust accounts</primary></indexterm>
  85 <indexterm><primary>net</primary></indexterm>
  86         UNIX systems that are hosting a Samba-3 server that is running as a member (PDC, BDC, or DMS) must have
  87         a machine security account in the domain authentication database (or directory). The creation of such
  88         security (or trust) accounts is also handled using the <command>net</command> command.
  89         </para>
  90
  91         <para>
  92 <indexterm><primary>interdomain trusts</primary></indexterm>
  93 <indexterm><primary>net</primary></indexterm>
  94 <indexterm><primary>administrative duties</primary></indexterm>
  95 <indexterm><primary>user management</primary></indexterm>
  96 <indexterm><primary>group management</primary></indexterm>
  97 <indexterm><primary>share management</primary></indexterm>
  98 <indexterm><primary>printer management</primary></indexterm>
  99 <indexterm><primary>printer migration</primary></indexterm>
 100 <indexterm><primary>SID management</primary></indexterm>
 101         The establishment of interdomain trusts is achieved using the <command>net</command> command also, as
 102         may a plethora of typical administrative duties such as user management, group management, share and
 103         printer management, file and printer migration, security identifier management, and so on.
 104         </para>
 105
 106         <para>
 107 <indexterm><primary>net</primary></indexterm>
 108 <indexterm><primary>man pages</primary></indexterm>
 109         The overall picture should be clear now: the <command>net</command> command plays a central role
 110         on the Samba-3 stage. This role will continue to be developed. The inclusion of this chapter is
 111         evidence of its importance, one that has grown in complexity to the point that it is no longer considered
 112         prudent to cover its use fully in the online UNIX man pages.
 113         </para>
 114
 115         </sect1>
 116
 117         <sect1>
 118         <title>Administrative Tasks and Methods</title>
 119
 120         <para>
 121 <indexterm><primary>net</primary></indexterm>
 122 <indexterm><primary>ADS</primary></indexterm>
 123 <indexterm><primary>Distributed Computing Environment</primary><see>DCE</see></indexterm>
 124 <indexterm><primary>Remote Procedure Call</primary><see>RPC</see></indexterm>
 125         The basic operations of the <command>net</command> command are documented here. This documentation is not
 126         exhaustive, and thus it is incomplete. Since the primary focus is on migration from Windows servers to a Samba
 127         server, the emphasis is on the use of the Distributed Computing Environment Remote Procedure Call (DCE RPC)
 128         mode of operation. When used against a server that is a member of an Active Directory domain, it is preferable
 129         (and often necessary) to use ADS mode operations. The <command>net</command> command supports both, but not
 130         for every operation. For most operations, if the mode is not specified, <command>net</command> will
 131         automatically fall back via the <constant>ads</constant>, <constant>rpc</constant>, and
 132         <constant>rap</constant> modes.  Please refer to the man page for a more comprehensive overview of the
 133         capabilities of this utility.
 134         </para>
 135
 136         </sect1>
 137
 138         <sect1>
 139         <title>UNIX and Windows Group Management</title>
 140
 141         <para>
 142 <indexterm><primary>Active Directory</primary></indexterm>
 143 <indexterm><primary>net</primary><secondary>rpc</secondary></indexterm>
 144 <indexterm><primary>net</primary><secondary>ads</secondary></indexterm>
 145 <indexterm><primary>net</primary><secondary>rap</secondary></indexterm>
 146 <indexterm><primary>RAP</primary></indexterm>
 147         As stated, the focus in most of this chapter is on use of the <command>net rpc</command> family of
 148         operations that are supported by Samba. Most of them are supported by the <command>net ads</command>
 149         mode when used in connection with Active Directory. The <command>net rap</command> operating mode is
 150         also supported for some of these operations. RAP protocols are used by IBM OS/2 and by several
 151         earlier SMB servers.
 152         </para>
 153
 154         <para>
 155 <indexterm><primary>net</primary></indexterm>
 156 <indexterm><primary>user management</primary></indexterm>
 157 <indexterm><primary>group management</primary></indexterm>
 158         Samba's <command>net</command> tool implements sufficient capability to permit all common administrative
 159         tasks to be completed from the command line. In this section each of the essential user and group management
 160         facilities are explored.
 161         </para>
 162
 163         <para>
 164 <indexterm><primary>groups</primary></indexterm>
 165 <indexterm><primary>domain</primary><secondary>groups</secondary></indexterm>
 166 <indexterm><primary>local</primary><secondary>groups</secondary></indexterm>
 167 <indexterm><primary>domain user accounts</primary></indexterm>
 168         Samba-3 recognizes two types of groups: <emphasis>domain groups</emphasis> and <emphasis>local
 169         groups</emphasis>. Domain groups can contain (have as members) only domain user accounts. Local groups
 170         can contain local users, domain users, and domain groups as members.
 171         </para>
 172
 173         <para>
 174         The purpose of a local group is to permit file permission to be set for a group account that, like the
 175         usual UNIX/Linux group, is persistent across redeployment of a Windows file server.
 176         </para>
 177
 178         <sect2>
 179         <title>Adding, Renaming, or Deletion of Group Accounts</title>
 180
 181         <para>
 182         Samba provides file and print services to Windows clients. The file system resources it makes available
 183         to the Windows environment must, of necessity, be provided in a manner that is compatible with the
 184         Windows networking environment. UNIX groups are created and deleted as required to serve operational
 185         needs in the UNIX operating system and its file systems.
 186         </para>
 187
 188         <para>
 189         In order to make available to the Windows environment Samba has a facility by which UNIX groups can
 190         be mapped to a logical entity, called a Windows (or domain) group. Samba supports two types of Windows
 191         groups, local and global. Global groups can contain as members, global users. This membership is
 192         affected in the normal UNIX manner, but adding UNIX users to UNIX groups. Windows user accounts consist
 193         of a mapping between a user SambaSAMAccount (logical entity) and a UNIX user account. Therefore,
 194         a UNIX user is mapped to a Windows user (i.e., is given a Windows user account and password) and the
 195         UNIX groups to which that user belongs, is mapped to a Windows group account. The result is that in
 196         the Windows account environment that user is also a member of the Windows group account by virtue
 197         of UNIX group memberships.
 198         </para>
 199
 200         <para>
 201         The following sub-sections that deal with management of Windows groups demonstrates the relationship
 202         between the UNIX group account and its members to the respective Windows group accounts. It goes on to
 203         show how UNIX group members automatically pass-through to Windows group membership as soon as a logical
 204         mapping has been created.
 205         </para>
 206
 207         <sect3>
 208         <title>Adding or Creating a New Group</title>
 209
 210         <para>
 211         Before attempting to add a Windows group account, the currently available groups can be listed as shown
 212         here:
 213 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group</tertiary></indexterm>
 214 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group list</tertiary></indexterm>
 215 <screen>
 216 &rootprompt; net rpc group list -Uroot%not24get
 217 Password:
 218 Domain Admins
 219 Domain Users
 220 Domain Guests
 221 Print Operators
 222 Backup Operators
 223 Replicator
 224 Domain Computers
 225 Engineers
 226 </screen>
 227         A Windows group account called <quote>SupportEngrs</quote> can be added by executing the following
 228 command:
 229 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group add</tertiary></indexterm>
 230 <screen>
 231 &rootprompt; net rpc group add "SupportEngrs" -Uroot%not24get
 232 </screen>
 233         The addition will result in immediate availability of the new group account as validated by executing
 234 this command:
 235 <screen>
 236 &rootprompt; net rpc group list -Uroot%not24get
 237 Password:
 238 Domain Admins
 239 Domain Users
 240 Domain Guests
 241 Print Operators
 242 Backup Operators
 243 Replicator
 244 Domain Computers
 245 Engineers
 246 SupportEngrs
 247 </screen>
 248         </para>
 249
 250         <para>
 251 <indexterm><primary>POSIX</primary></indexterm>
 252 <indexterm><primary>smbldap-groupadd</primary></indexterm>
 253 <indexterm><primary>getent</primary></indexterm>
 254         The following demonstrates that the POSIX (UNIX/Linux system account) group has been created by calling
 255         the <smbconfoption name="add group script">/opt/IDEALX/sbin/smbldap-groupadd -p "%g"</smbconfoption> interface
 256         script:
 257 <screen>
 258 &rootprompt; getent group
 259 ...
 260 Domain Admins:x:512:root
 261 Domain Users:x:513:jht,lct,ajt,met
 262 Domain Guests:x:514:
 263 Print Operators:x:550:
 264 Backup Operators:x:551:
 265 Replicator:x:552:
 266 Domain Computers:x:553:
 267 Engineers:x:1002:jht
 268 SupportEngrs:x:1003:
 269 </screen>
 270         The following demonstrates that the use of the <command>net</command> command to add a group account
 271 results in immediate mapping of the POSIX group that has been created to the Windows group account as shown
 272 here:
 273 <indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>list</tertiary></indexterm>
 274 <screen>
 275 &rootprompt; net groupmap list
 276 Domain Admins (S-1-5-21-72630-4128915-11681869-512) -> Domain Admins
 277 Domain Users (S-1-5-21-72630-4128915-11681869-513) -> Domain Users
 278 Domain Guests (S-1-5-21-72630-4128915-11681869-514) -> Domain Guests
 279 Print Operators (S-1-5-21-72630-4128915-11681869-550) -> Print Operators
 280 Backup Operators (S-1-5-21-72630-4128915-11681869-551) -> Backup Operators
 281 Replicator (S-1-5-21-72630-4128915-11681869-552) -> Replicator
 282 Domain Computers (S-1-5-21-72630-4128915-11681869-553) -> Domain Computers
 283 Engineers (S-1-5-21-72630-4128915-11681869-3005) -> Engineers
 284 SupportEngrs (S-1-5-21-72630-4128915-11681869-3007) -> SupportEngrs
 285 </screen>
 286         </para>
 287
 288         </sect3>
 289
 290         <sect3>
 291         <title>Mapping Windows Groups to UNIX Groups</title>
 292
 293         <para>
 294 <indexterm><primary>mapped</primary></indexterm>
 295 <indexterm><primary>Windows groups</primary></indexterm>
 296 <indexterm><primary>system groups</primary></indexterm>
 297 <indexterm><primary>access controls</primary></indexterm>
 298         Windows groups must be mapped to UNIX system (POSIX) groups so that file system access controls
 299         can be asserted in a manner that is consistent with the methods appropriate to the operating
 300         system that is hosting the Samba server.
 301         </para>
 302
 303         <para>
 304 <indexterm><primary>access controls</primary></indexterm>
 305 <indexterm><primary>UID</primary></indexterm>
 306 <indexterm><primary>GID</primary></indexterm>
 307 <indexterm><primary>locally known UID</primary></indexterm>
 308         All file system (file and directory) access controls, within the file system of a UNIX/Linux server that is
 309         hosting a Samba server, are implemented using a UID/GID identity tuple. Samba does not in any way override
 310         or replace UNIX file system semantics. Thus it is necessary that all Windows networking operations that
 311         access the file system provide a mechanism that maps a Windows user to a particular UNIX/Linux group
 312         account. The user account must also map to a locally known UID.
 313         </para>
 314
 315         <para>
 316 <indexterm><primary>default mappings</primary></indexterm>
 317 <indexterm><primary>Domain Admins</primary></indexterm>
 318 <indexterm><primary>Domain Users</primary></indexterm>
 319 <indexterm><primary>Domain Guests</primary></indexterm>
 320 <indexterm><primary>Windows group</primary></indexterm>
 321 <indexterm><primary>UNIX group</primary></indexterm>
 322 <indexterm><primary>mapping</primary></indexterm>
 323         Samba depends on default mappings for the <constant>Domain Admins, Domain Users</constant>, and
 324         <constant>Domain Guests</constant> global groups. Additional groups may be added as shown in the
 325         examples just given. There are times when it is necessary to map an existing UNIX group account
 326         to a Windows group. This operation, in effect, creates a Windows group account as a consequence
 327         of creation of the mapping.
 328         </para>
 329
 330         <para>
 331 <indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>modify</tertiary></indexterm>
 332 <indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>add</tertiary></indexterm>
 333 <indexterm><primary>net</primary><secondary>groupmap</secondary><tertiary>delete</tertiary></indexterm>
 334         The operations that are permitted include: <constant>add</constant>, <constant>modify</constant>,
 335         and <constant>delete</constant>. An example of each operation is shown here.
 336         </para>
 337
 338         <para>
 339         An existing UNIX group may be mapped to an existing Windows group by this example:
 340 <screen>
 341 &rootprompt; net groupmap modify ntgroup="Domain Users" unixgroup=users
 342 </screen>
 343         An existing UNIX group may be mapped to a new Windows group as shown here:
 344 <screen>
 345 &rootprompt; net groupmap add ntgroup="EliteEngrs" unixgroup=Engineers type=d
 346 </screen>
 347         Supported mapping types are 'd' (domain global) and 'l' (domain local).
 348         A Windows group may be deleted, and then a new Windows group can be mapped to the UNIX group by
 349         executing these commands:
 350 <screen>
 351 &rootprompt; net groupmap delete ntgroup=Engineers
 352 &rootprompt; net groupmap add ntgroup=EngineDrivers unixgroup=Engineers type=d
 353 </screen>
 354         The deletion and addition operations affected only the logical entities known as Windows groups, or domain
 355         groups. These operations are inert to UNIX system groups, meaning that they neither delete nor create UNIX
 356         system groups. The mapping of a UNIX group to a Windows group makes the UNIX group available as Windows
 357         groups so that files and folders on domain member clients (workstations and servers) can be given
 358         domain-wide access controls for domain users and groups.
 359         </para>
 360
 361         <para>
 362         Two types of Windows groups can be created: <constant>domain (global)</constant> and <constant>local</constant>.
 363         In the previous examples the Windows groups created were of type <constant>domain</constant> or global. The
 364         following command will create a Windows group of type <constant>local</constant>.
 365 <screen>
 366 &rootprompt; net groupmap add ntgroup=Pixies unixgroup=pixies type=l
 367 </screen>
 368         Supported mapping types are 'd' (domain global) and 'l' (domain local), a domain local group is Samba is
 369         treated as local to the individual Samba serverr. Local groups can be used with Samba to enable multiple
 370         nested group support.
 371         </para>
 372
 373         </sect3>
 374
 375         <sect3>
 376         <title>Deleting a Group Account</title>
 377
 378         <para>
 379 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group delete</tertiary></indexterm>
 380         A group account may be deleted by executing the following command:
 381 <screen>
 382 &rootprompt; net rpc group delete SupportEngineers -Uroot%not24get
 383 </screen>
 384         </para>
 385
 386         <para>
 387         Validation of the deletion is advisable. The same commands may be executed as shown above.
 388         </para>
 389
 390         </sect3>
 391
 392         <sect3>
 393         <title>Rename Group Accounts</title>
 394
 395         <note><para>
 396         This command is not documented in the man pages; it is implemented in the source code, but it does not
 397         work. The example given documents (from the source code) how it should work. Watch the release notes
 398         of a future release to see when this may have been fixed.
 399         </para></note>
 400
 401         <para>
 402         Sometimes it is necessary to rename a group account. Good administrators know how painful some managers'
 403         demands can be if this simple request is ignored. The following command demonstrates how the Windows group
 404         <quote>SupportEngrs</quote> can be renamed to <quote>CustomerSupport</quote>:
 405 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group rename</tertiary></indexterm>
 406 <screen>
 407 &rootprompt; net rpc group rename SupportEngrs \
 408     CustomerSupport -Uroot%not24get
 409 </screen>
 410         </para>
 411
 412         </sect3>
 413
 414         </sect2>
 415
 416         <sect2 id="grpmemshipchg">
 417         <title>Manipulating Group Memberships</title>
 418
 419         <para>
 420         Three operations can be performed regarding group membership. It is possible to (1) add Windows users
 421         to a Windows group, to (2) delete Windows users from Windows groups, and to (3) list the Windows users that are
 422         members of a Windows group.
 423         </para>
 424
 425         <para>
 426         To avoid confusion, it makes sense to check group membership before attempting to make any changes.
 427         The <command>getent group</command> will list UNIX/Linux group membership. UNIX/Linux group members are
 428         seen also as members of a Windows group that has been mapped using the <command>net groupmap</command>
 429         command (see <link linkend="groupmapping"/>). The following list of UNIX/Linux group membership shows
 430         that the user <constant>ajt</constant> is a member of the UNIX/Linux group <constant>Engineers</constant>.
 431 <screen>
 432 &rootprompt; getent group
 433 ...
 434 Domain Admins:x:512:root
 435 Domain Users:x:513:jht,lct,ajt,met,vlendecke
 436 Domain Guests:x:514:
 437 Print Operators:x:550:
 438 Backup Operators:x:551:
 439 Replicator:x:552:
 440 Domain Computers:x:553:
 441 Engineers:x:1000:jht,ajt
 442 </screen>
 443         The UNIX/Linux groups have been mapped to Windows groups, as is shown here:
 444 <screen>
 445 &rootprompt; net groupmap list
 446 Domain Admins (S-1-5-21-72630-412605-116429-512) -> Domain Admins
 447 Domain Users (S-1-5-21-72630-412605-116429-513) -> Domain Users
 448 Domain Guests (S-1-5-21-72630-412605-116429-514) -> Domain Guests
 449 Print Operators (S-1-5-21-72630-412605-116429-550) -> Print Operators
 450 Backup Operators (S-1-5-21-72630-412605-116429-551) -> Backup Operators
 451 Replicator (S-1-5-21-72630-412605-116429-552) -> Replicator
 452 Domain Computers (S-1-5-21-72630-412605-116429-553) -> Domain Computers
 453 Engineers (S-1-5-21-72630-412605-116429-3001) -> Engineers
 454 </screen>
 455         </para>
 456
 457         <para>
 458         Given that the user <constant>ajt</constant> is already a member of the UNIX/Linux group and, via the
 459         group mapping, a member of the Windows group, an attempt to add this account again should fail. This is
 460         demonstrated here:
 461 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
 462 <screen>
 463 &rootprompt; net rpc group addmem "MIDEARTH\Engineers" ajt -Uroot%not24get
 464 Could not add ajt to MIDEARTH\Engineers: NT_STATUS_MEMBER_IN_GROUP
 465 </screen>
 466         This shows that the group mapping between UNIX/Linux groups and Windows groups is effective and
 467         transparent.
 468         </para>
 469
 470         <para>
 471         To permit the user <constant>ajt</constant> to be added using the <command>net rpc group</command> utility,
 472         this account must first be removed. The removal and confirmation of its effect is shown here:
 473 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group delmem</tertiary></indexterm>
 474 <screen>
 475 &rootprompt; net rpc group delmem "MIDEARTH\Engineers" ajt -Uroot%not24get
 476 &rootprompt; getent group Engineers
 477 Engineers:x:1000:jht
 478 &rootprompt; net rpc group members Engineers -Uroot%not24get
 479 MIDEARTH\jht
 480 </screen>
 481         In this example both at the UNIX/Linux system level, the group no longer has the <constant>ajt</constant>
 482         as a member. The above also shows this to be the case for Windows group membership.
 483         </para>
 484
 485         <para>
 486         The account is now added again, using the <command>net rpc group</command> utility:
 487 <screen>
 488 &rootprompt; net rpc group addmem "MIDEARTH\Engineers" ajt -Uroot%not24get
 489 &rootprompt; getent group Engineers
 490 Engineers:x:1000:jht,ajt
 491 &rootprompt; net rpc group members Engineers -Uroot%not24get
 492 MIDEARTH\jht
 493 MIDEARTH\ajt
 494 </screen>
 495         </para>
 496
 497         <para>
 498         In this example the members of the Windows <constant>Domain Users</constant> account are validated using
 499         the <command>net rpc group</command> utility. Note the this contents of the UNIX/Linux group was shown
 500         four paragraphs earlier. The Windows (domain) group membership is shown here:
 501 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group members</tertiary></indexterm>
 502 <screen>
 503 &rootprompt; net rpc group members "Domain Users" -Uroot%not24get
 504 MIDEARTH\jht
 505 MIDEARTH\lct
 506 MIDEARTH\ajt
 507 MIDEARTH\met
 508 MIDEARTH\vlendecke
 509 </screen>
 510         This express example shows that Windows group names are treated by Samba (as with
 511         MS Windows) in a case-insensitive manner:
 512 <screen>
 513 &rootprompt; net rpc group members "DomAiN USerS" -Uroot%not24get
 514 MIDEARTH\jht
 515 MIDEARTH\lct
 516 MIDEARTH\ajt
 517 MIDEARTH\met
 518 MIDEARTH\vlendecke
 519 </screen>
 520         </para>
 521
 522         <note><para>
 523         An attempt to specify the group name as <constant>MIDEARTH\Domain Users</constant> in place of
 524         just simply <constant>Domain Users</constant> will fail. The default behavior of the net rpc group
 525         is to direct the command at the local machine. The Windows group is treated as being local to the machine.
 526         If it is necessary to query another machine, its name can be specified using the <constant>-S
 527         servername</constant> parameter to the <command>net</command> command.
 528         </para></note>
 529
 530         </sect2>
 531
 532         <sect2 id="nestedgrpmgmgt">
 533         <title>Nested Group Support</title>
 534
 535         <para>
 536         It is possible in Windows (and now in Samba also) to create a local group that has members (contains),
 537         domain users, and domain global groups.  Creation of the local group <constant>demo</constant> is
 538         achieved by executing:
 539 <screen>
 540 &rootprompt; net rpc group add demo -L -S MORDON -Uroot%not24get
 541 </screen>
 542         The -L switch means create a local group. Use the -S argument to direct the operation to a particular
 543         server. The parameters to the -U argument should be for a user who has appropriate administrative right
 544         and privileges on the machine.
 545         </para>
 546
 547         <para>
 548         Addition and removal of group members can be achieved using the <constant>addmem</constant> and
 549         <constant>delmem</constant> subcommands of <command>net rpc group</command> command. For example,
 550         addition of <quote>DOM\Domain Users</quote> to the local group <constant>demo</constant> would be
 551         done by executing:
 552 <screen>
 553 &rootprompt; net rpc group addmem demo "DOM\Domain Users" -Uroot%not24get
 554 </screen>
 555         </para>
 556
 557         <para>
 558         The members of a nested group can be listed by executing the following:
 559 <screen>
 560 &rootprompt; net rpc group members demo -Uroot%not24get
 561 DOM\Domain Users
 562 DOM\Engineers
 563 DOM\jamesf
 564 DOM\jht
 565 </screen>
 566         </para>
 567
 568         <para>
 569         Nested group members can be removed (deleted) as shown here:
 570 <screen>
 571 &rootprompt; net rpc group delmem demo "DOM\jht" -Uroot%not24get
 572 </screen>
 573         </para>
 574
 575         <sect3>
 576         <title>Managing Nest Groups on Workstations from the Samba Server</title>
 577
 578         <para>
 579         Windows network administrators often ask on the Samba mailing list how it is possible to grant everyone
 580         administrative rights on their own workstation. This is of course a very bad practice, but commonly done
 581         to avoid user complaints. Here is how it can be done remotely from a Samba PDC or BDC:
 582 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
 583 <screen>
 584 &rootprompt; net rpc group addmem "Administrators" "Domain Users" \
 585     -S WINPC032 -Uadministrator%secret
 586 </screen>
 587         </para>
 588
 589         <para>
 590         This can be scripted, and can therefore be performed as a user logs onto the domain from a Windows
 591         workstation. Here is a simple example that shows how this can be done.
 592         </para>
 593
 594         <procedure>
 595         <title>Automating User Addition to the Workstation Power Users Group</title>
 596
 597                 <step><para>
 598                 Create the script shown in <link linkend="autopoweruserscript"></link> and locate it in
 599                 the directory <filename>/etc/samba/scripts</filename>, named as <filename>autopoweruser.sh</filename>.
 600 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>group addmem</tertiary></indexterm>
 601 <indexterm><primary>autopoweruser.sh</primary></indexterm>
 602 <indexterm><primary>/etc/samba/scripts</primary></indexterm>
 603                 </para></step>
 604
 605 <example id="autopoweruserscript">
 606 <title>Script to Auto-add Domain Users to Workstation Power Users Group</title>
 607 <screen>
 608 #!/bin/bash
 609
 610 /usr/bin/net rpc group addmem "Power Users"  "DOMAIN_NAME\$1" -UAdministrator%secret -S $2
 611
 612 exit 0
 613 </screen>
 614 </example>
 615
 616                 <step><para>
 617                 Set the permissions on this script to permit it to be executed as part of the logon process:
 618 <screen>
 619 &rootprompt; chown root:root /etc/samba/autopoweruser.sh
 620 &rootprompt; chmod 755 /etc/samba/autopoweruser.sh
 621 </screen>
 622                 </para></step>
 623
 624                 <step><para>
 625                 Modify the &smb.conf; file so the <literal>NETLOGON</literal> stanza contains the parameters
 626                 shown in <link linkend="magicnetlogon">the Netlogon Example smb.conf file</link>.
 627                 </para></step>
 628
 629 <example id="magicnetlogon">
 630 <title>A Magic Netlogon Share</title>
 631 <smbconfblock>
 632 <smbconfsection name="[netlogon]"/>
 633 <smbconfoption name="comment">Netlogon Share</smbconfoption>
 634 <smbconfoption name="path">/var/lib/samba/netlogon</smbconfoption>
 635 <smbconfoption name="root preexec">/etc/samba/scripts/autopoweruser.sh %U %m</smbconfoption>
 636 <smbconfoption name="read only">Yes</smbconfoption>
 637 <smbconfoption name="guest ok">Yes</smbconfoption>
 638 </smbconfblock>
 639 </example>
 640
 641                 <step><para>
 642                 Ensure that every Windows workstation Adminsitrator account has the same password that you
 643                 have used in the script shown in <link linkend="magicnetlogon">the Netlogon Example smb.conf
 644                 file</link>
 645                 </para></step>
 646
 647 </procedure>
 648
 649         <para>
 650         This script will be executed every time a user logs onto the network. Therefore every user will
 651         have local Windows workstation management rights. This could of course be assigned using a group,
 652         in which case there is little justification for the use of this procedure. The key justification
 653         for the use of this method is that it will guarantee that all users have appropriate rights on
 654         the workstation.
 655         </para>
 656
 657         </sect3>
 658
 659         </sect2>
 660
 661         </sect1>
 662
 663         <sect1>
 664         <title>UNIX and Windows User Management</title>
 665
 666         <para>
 667 <indexterm><primary>user account</primary></indexterm>
 668 <indexterm><primary>UNIX/Linux user account</primary></indexterm>
 669 <indexterm><primary>UID</primary></indexterm>
 670 <indexterm><primary>POSIX account</primary></indexterm>
 671 <indexterm><primary>range</primary></indexterm>
 672 <indexterm><primary>Windows user accounts</primary></indexterm>
 673 <indexterm><primary>winbindd</primary></indexterm>
 674 <indexterm><primary>account information</primary></indexterm>
 675         Every Windows network user account must be translated to a UNIX/Linux user account. In actual fact,
 676         the only account information the UNIX/Linux Samba server needs is a UID.  The UID is available either
 677         from a system (POSIX) account or from a pool (range) of UID numbers that is set aside for the purpose
 678         of being allocated for use by Windows user accounts. In the case of the UID pool, the UID for a
 679         particular user will be allocated by <command>winbindd</command>.
 680         </para>
 681
 682         <para>
 683         Although this is not the appropriate place to discuss the <smbconfoption name="username map"/> facility,
 684         this interface is an important method of mapping a Windows user account to a UNIX account that has a
 685         different name. Refer to the man page for the &smb.conf; file for more information regarding this
 686         facility. User name mappings cannot be managed using the <command>net</command> utility.
 687         </para>
 688
 689         <sect2 id="sbeuseraddn">
 690         <title>Adding User Accounts</title>
 691
 692         <para>
 693         The syntax for adding a user account via the <command>net</command> (according to the man page) is shown
 694         here:
 695 <screen>
 696 net [&lt;method&gt;] user ADD &lt;name&gt; [-c container] [-F user flags] \
 697     [misc. options] [targets]
 698 </screen>
 699         The user account password may be set using this syntax:
 700 <screen>
 701 net rpc password &lt;username&gt; [&lt;password&gt;] -Uadmin_username%admin_pass
 702 </screen>
 703         </para>
 704
 705         <para>
 706         The following demonstrates the addition of an account to the server <constant>FRODO</constant>:
 707 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user add</tertiary></indexterm>
 708 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user password</tertiary></indexterm>
 709 <screen>
 710 &rootprompt; net rpc user add jacko -S FRODO -Uroot%not24get
 711 Added user jacko
 712 </screen>
 713         The account password can be set with the following methods (all show the same operation):
 714 <screen>
 715 &rootprompt; net rpc password jacko f4sth0rse -S FRODO -Uroot%not24get
 716 &rootprompt; net rpc user password jacko f4sth0rse \
 717     -S FRODO -Uroot%not24get
 718 </screen>
 719         </para>
 720
 721         </sect2>
 722
 723         <sect2>
 724         <title>Deletion of User Accounts</title>
 725
 726         <para>
 727         Deletion of a user account can be done using the following syntax:
 728 <screen>
 729 net [&lt;method&gt;] user DELETE &lt;name&gt; [misc. options] [targets]
 730 </screen>
 731         The following command will delete the user account <constant>jacko</constant>:
 732 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user delete</tertiary></indexterm>
 733 <screen>
 734 &rootprompt; net rpc user delete jacko -Uroot%not24get
 735 Deleted user account
 736 </screen>
 737         </para>
 738
 739         </sect2>
 740
 741         <sect2>
 742         <title>Managing User Accounts</title>
 743
 744         <para>
 745         Two basic user account operations are routinely used: change of password and querying which groups a user
 746         is a member of. The change of password operation is shown in <link linkend="sbeuseraddn"/>.
 747         </para>
 748
 749         <para>
 750         The ability to query Windows group membership can be essential. Here is how a remote server may be
 751         interrogated to find which groups a user is a member of:
 752 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user info</tertiary></indexterm>
 753 <screen>
 754 &rootprompt; net rpc user info jacko -S SAURON -Uroot%not24get
 755 net rpc user info jacko -S SAURON -Uroot%not24get
 756 Domain Users
 757 Domain Admins
 758 Engineers
 759 TorridGroup
 760 BOP Shop
 761 Emergency Services
 762 </screen>
 763         </para>
 764
 765         </sect2>
 766
 767         <sect2>
 768         <title>User Mapping</title>
 769
 770         <para>
 771 <indexterm><primary>logon name</primary></indexterm>
 772 <indexterm><primary>/etc/samba/smbusers</primary></indexterm>
 773 <indexterm><primary>username map</primary></indexterm>
 774         In some situations it is unavoidable that a user's Windows logon name will differ from the login ID
 775         that user has on the Samba server. It is possible to create a special file on the Samba server that
 776         will permit the Windows user name to be mapped to a different UNIX/Linux user name. The &smb.conf;
 777         file must also be amended so that the <constant>[global]</constant> stanza contains the parameter:
 778 <screen>
 779 username map = /etc/samba/smbusers
 780 </screen>
 781         The content of the <filename>/etc/samba/smbusers</filename> file is shown here:
 782 <screen>
 783 parsonsw: "William Parsons"
 784 marygee: geeringm
 785 </screen>
 786         In this example the Windows user account <quote>William Parsons</quote> will be mapped to the UNIX user
 787         <constant>parsonsw</constant>, and the Windows user account <quote>geeringm</quote> will be mapped to the
 788         UNIX user <constant>marygee</constant>.
 789         </para>
 790
 791         </sect2>
 792
 793         </sect1>
 794
 795         <sect1>
 796         <title>Administering User Rights and Privileges</title>
 797
 798         <para>
 799 <indexterm><primary>credentials</primary></indexterm>
 800 <indexterm><primary>manage printers</primary></indexterm>
 801 <indexterm><primary>manage shares</primary></indexterm>
 802 <indexterm><primary>manage groups</primary></indexterm>
 803 <indexterm><primary>manage users</primary></indexterm>
 804         With all versions of Samba earlier than 3.0.11 the only account on a Samba server that could
 805         manage users, groups, shares, printers, and such was the <constant>root</constant> account. This caused
 806         problems for some users and was a frequent source of scorn over the necessity to hand out the
 807         credentials for the most security-sensitive account on a UNIX/Linux system.
 808         </para>
 809
 810         <para>
 811 <indexterm><primary>delegate administrative privileges</primary></indexterm>
 812 <indexterm><primary>normal user</primary></indexterm>
 813 <indexterm><primary>rights and privilege</primary></indexterm>
 814 <indexterm><primary>privilege management</primary></indexterm>
 815 <indexterm><primary>groups of users</primary></indexterm>
 816         New to Samba version 3.0.11 is the ability to delegate administrative privileges as necessary to either
 817         a normal user or to groups of users. The significance of the administrative privileges is documented
 818         in <link linkend="rights"/>. Examples of use of the <command>net</command> for user rights and privilege
 819         management is appropriate to this chapter.
 820         </para>
 821
 822         <note><para>
 823         When user rights and privileges are correctly set, there is no longer a need for a Windows
 824         network account for the <constant>root</constant> user (nor for any synonym of it) with a UNIX UID=0.
 825         Initial user rights and privileges can be assigned by any account that is a member of the <constant>
 826         Domain Admins</constant> group. Rights can be assigned to user as well as group accounts.
 827         </para></note>
 828
 829         <para>
 830         By default, no privileges and rights are assigned. This is demonstrated by executing the command
 831         shown here:
 832 <screen>
 833 &rootprompt; net rpc rights list accounts -U root%not24get
 834 BUILTIN\Print Operators
 835 No privileges assigned
 836
 837 BUILTIN\Account Operators
 838 No privileges assigned
 839
 840 BUILTIN\Backup Operators
 841 No privileges assigned
 842
 843 BUILTIN\Server Operators
 844 No privileges assigned
 845
 846 BUILTIN\Administrators
 847 No privileges assigned
 848
 849 Everyone
 850 No privileges assigned
 851 </screen>
 852         </para>
 853
 854         <para>
 855         The <command>net</command> command can be used to obtain the currently supported capabilities for rights
 856         and privileges using this method:
 857 <indexterm><primary>SeMachineAccountPrivilege</primary></indexterm>
 858 <indexterm><primary>SePrintOperatorPrivilege</primary></indexterm>
 859 <indexterm><primary>SeAddUsersPrivilege</primary></indexterm>
 860 <indexterm><primary>SeRemoteShutdownPrivilege</primary></indexterm>
 861 <indexterm><primary>SeDiskOperatorPrivilege</primary></indexterm>
 862 <indexterm><primary>SeBackupPrivilege</primary></indexterm>
 863 <indexterm><primary>SeRestorePrivilege</primary></indexterm>
 864 <indexterm><primary>SeTakeOwnershipPrivilege</primary></indexterm>
 865 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights list</tertiary></indexterm>
 866 <screen>
 867 &rootprompt; net rpc rights list -U root%not24get
 868      SeMachineAccountPrivilege  Add machines to domain
 869       SePrintOperatorPrivilege  Manage printers
 870            SeAddUsersPrivilege  Add users and groups to the domain
 871      SeRemoteShutdownPrivilege  Force shutdown from a remote system
 872        SeDiskOperatorPrivilege  Manage disk shares
 873              SeBackupPrivilege  Back up files and directories
 874             SeRestorePrivilege  Restore files and directories
 875       SeTakeOwnershipPrivilege  Take ownership of files or other objects
 876 </screen>
 877         Machine account privilege is necessary to permit a Windows NT4 or later network client to be added to the
 878         domain. The disk operator privilege is necessary to permit the user to manage share ACLs and file and
 879         directory ACLs for objects not owned by the user.
 880         </para>
 881
 882         <para>
 883         For reference purposes, a Windows 2000 Domain Controller reports that it supports the following
 884         privileges:
 885 <screen>
 886          SeCreateTokenPrivilege  Create a token object
 887   SeAssignPrimaryTokenPrivilege  Replace a process level token
 888           SeLockMemoryPrivilege  Lock pages in memory
 889        SeIncreaseQuotaPrivilege  Increase quotas
 890       SeMachineAccountPrivilege  Add workstations to domain
 891                  SeTcbPrivilege  Act as part of the operating system
 892             SeSecurityPrivilege  Manage auditing and security log
 893        SeTakeOwnershipPrivilege  Take ownership of files or other objects
 894           SeLoadDriverPrivilege  Load and unload device drivers
 895        SeSystemProfilePrivilege  Profile system performance
 896           SeSystemtimePrivilege  Change the system time
 897 SeProfileSingleProcessPrivilege  Profile single process
 898 SeIncreaseBasePriorityPrivilege  Increase scheduling priority
 899       SeCreatePagefilePrivilege  Create a pagefile
 900      SeCreatePermanentPrivilege  Create permanent shared objects
 901               SeBackupPrivilege  Back up files and directories
 902              SeRestorePrivilege  Restore files and directories
 903             SeShutdownPrivilege  Shut down the system
 904                SeDebugPrivilege  Debug programs
 905                SeAuditPrivilege  Generate security audits
 906    SeSystemEnvironmentPrivilege  Modify firmware environment values
 907         SeChangeNotifyPrivilege  Bypass traverse checking
 908       SeRemoteShutdownPrivilege  Force shutdown from a remote system
 909               SeUndockPrivilege  Remove computer from docking station
 910            SeSyncAgentPrivilege  Synchronize directory service data
 911     SeEnableDelegationPrivilege  Enable computer and user accounts to
 912                                  be trusted for delegation
 913         SeManageVolumePrivilege  Perform volume maintenance tasks
 914          SeImpersonatePrivilege  Impersonate a client after authentication
 915         SeCreateGlobalPrivilege  Create global objects
 916 </screen>
 917         The Samba Team are implementing only those privileges that are logical and useful in the UNIX/Linux
 918         envronment. Many of the Windows 200X/XP privileges have no direct equivalence in UNIX.
 919         </para>
 920
 921         <para>
 922         In this example, all rights are assigned to the <constant>Domain Admins</constant> group. This is a good
 923         idea since members of this group are generally expected to be all-powerful. This assignment makes that
 924         the reality:
 925 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights grant</tertiary></indexterm>
 926 <screen>
 927 &rootprompt; net rpc rights grant "MIDEARTH\Domain Admins" \
 928     SeMachineAccountPrivilege SePrintOperatorPrivilege \
 929     SeAddUsersPrivilege SeRemoteShutdownPrivilege \
 930     SeDiskOperatorPrivilege  -U root%not24get
 931 Successfully granted rights.
 932 </screen>
 933         Next, the domain user <constant>jht</constant> is given the privileges needed for day-to-day
 934         administration:
 935 <screen>
 936 &rootprompt; net rpc rights grant "MIDEARTH\jht" \
 937     SeMachineAccountPrivilege SePrintOperatorPrivilege \
 938     SeAddUsersPrivilege SeDiskOperatorPrivilege \
 939     -U root%not24get
 940 Successfully granted rights.
 941 </screen>
 942         </para>
 943
 944         <para>
 945         The following step permits validation of the changes just made:
 946 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>rights list accounts</tertiary></indexterm>
 947 <screen>
 948 &rootprompt; net rpc rights list accounts -U root%not24get
 949 MIDEARTH\jht
 950 SeMachineAccountPrivilege
 951 SePrintOperatorPrivilege
 952 SeAddUsersPrivilege
 953 SeDiskOperatorPrivilege
 954
 955 BUILTIN\Print Operators
 956 No privileges assigned
 957
 958 BUILTIN\Account Operators
 959 No privileges assigned
 960
 961 BUILTIN\Backup Operators
 962 No privileges assigned
 963
 964 BUILTIN\Server Operators
 965 No privileges assigned
 966
 967 BUILTIN\Administrators
 968 No privileges assigned
 969
 970 Everyone
 971 No privileges assigned
 972
 973 MIDEARTH\Domain Admins
 974 SeMachineAccountPrivilege
 975 SePrintOperatorPrivilege
 976 SeAddUsersPrivilege
 977 SeRemoteShutdownPrivilege
 978 SeDiskOperatorPrivilege
 979 </screen>
 980         </para>
 981
 982         </sect1>
 983
 984         <sect1>
 985         <title>Managing Trust Relationships</title>
 986
 987         <para>
 988         There are essentially two types of trust relationships: the first is between domain controllers and domain
 989         member machines (network clients), the second is between domains (called interdomain trusts). All
 990         Samba servers that participate in domain security require a domain membership trust account, as do like
 991         Windows NT/200x/XP workstations.
 992         </para>
 993
 994         <sect2>
 995         <title>Machine Trust Accounts</title>
 996
 997         <para>
 998         The net command looks in the &smb.conf; file to obtain its own configuration settings. Thus, the following
 999         command 'know' which domain to join from the &smb.conf; file.
1000         </para>
1001
1002         <para>
1003         A Samba server domain trust account can be validated as shown in this example:
1004 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>testjoin</tertiary></indexterm>
1005 <screen>
1006 &rootprompt; net rpc testjoin
1007 Join to 'MIDEARTH' is OK
1008 </screen>
1009         Where there is no domain membership account, or when the account credentials are not valid, the following
1010         results will be observed:
1011 <screen>
1012 net rpc testjoin -S DOLPHIN
1013 Join to domain 'WORLDOCEAN' is not valid
1014 </screen>
1015         </para>
1016
1017         <para>
1018         The equivalent command for joining a Samba server to a Windows ADS domain is shown here:
1019 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>testjoin</tertiary></indexterm>
1020 <screen>
1021 &rootprompt; net ads testjoin
1022 Using short domain name -- TAKEAWAY
1023 Joined 'LEMONADE' to realm 'TAKEAWAY.BIZ'
1024 </screen>
1025         In the event that the ADS trust was not established, or is broken for one reason or another, the following
1026         error message may be obtained:
1027 <screen>
1028 &rootprompt; net ads testjoin -UAdministrator%secret
1029 Join to domain is not valid
1030 </screen>
1031         </para>
1032
1033         <para>
1034         The following demonstrates the process of creating a machine trust account in the target domain for the
1035         Samba server from which the command is executed:
1036 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join</tertiary></indexterm>
1037 <screen>
1038 &rootprompt; net rpc join -S FRODO -Uroot%not24get
1039 Joined domain MIDEARTH.
1040 </screen>
1041         The joining of a Samba server to a Samba domain results in the creation of a machine account. An example
1042         of this is shown here:
1043 <screen>
1044 &rootprompt; pdbedit -Lw merlin\$
1045 merlin$:1009:9B4489D6B90461FD6A3EC3AB96147E16:\
1046 176D8C554E99914BDF3407DEA2231D80:[S          ]:LCT-42891919:
1047 </screen>
1048         The S in the square brackets means this is a server (PDC/BDC) account. The domain join can be cast to join
1049         purely as a workstation, in which case the S is replaced with a W (indicating a workstation account). The
1050         following command can be used to affect this:
1051 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join member</tertiary></indexterm>
1052 <screen>
1053 &rootprompt; net rpc join member -S FRODO -Uroot%not24get
1054 Joined domain MIDEARTH.
1055 </screen>
1056         Note that the command-line parameter <constant>member</constant> makes this join specific. By default
1057         the type is deduced from the &smb.conf; file configuration. To specifically join as a PDC or BDC, the
1058         command-line parameter will be <constant>[PDC | BDC]</constant>. For example:
1059 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>join bdc</tertiary></indexterm>
1060 <screen>
1061 &rootprompt; net rpc join bdc -S FRODO -Uroot%not24get
1062 Joined domain MIDEARTH.
1063 </screen>
1064         It is best to let Samba figure out the domain join type from the settings in the &smb.conf; file.
1065         </para>
1066
1067         <para>
1068         The command to join a Samba server to a Windows ADS domain is shown here:
1069 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>join</tertiary></indexterm>
1070 <screen>
1071 &rootprompt; net ads join -UAdministrator%not24get
1072 Using short domain name -- GDANSK
1073 Joined 'FRANDIMITZ' to realm 'GDANSK.ABMAS.BIZ'
1074 </screen>
1075         </para>
1076
1077         <para>
1078         There is no specific option to remove a machine account from an NT4 domain. When a domain member that is a
1079         Windows machine is withdrawn from the domain, the domain membership account is not automatically removed
1080         either. Inactive domain member accounts can be removed using any convenient tool. If necessary, the
1081         machine account can be removed using the following <command>net</command> command:
1082 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>user delete</tertiary></indexterm>
1083 <screen>
1084 &rootprompt; net rpc user delete HERRING\$ -Uroot%not24get
1085 Deleted user account.
1086 </screen>
1087         The removal is made possible because machine accounts are just like user accounts with a trailing $
1088         character. The account management operations treat user and machine accounts in like manner.
1089         </para>
1090
1091         <para>
1092         A Samba-3 server that is a Windows ADS domain member can execute the following command to detach from the
1093         domain:
1094 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>leave</tertiary></indexterm>
1095 <screen>
1096 &rootprompt; net ads leave
1097 </screen>
1098         </para>
1099
1100         <para>
1101         Detailed information regarding an ADS domain can be obtained by a Samba DMS machine by executing the
1102         following:
1103 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>status</tertiary></indexterm>
1104 <screen>
1105 &rootprompt; net ads status
1106 </screen>
1107         The volume of information is extensive. Please refer to the book <quote>Samba-3 by Example</quote>,
1108         Chapter 7 for more information regarding its use. This book may be obtained either in print or online from
1109         the <ulink url="http://www.samba.org/samba/docs/Samba3-ByExample.pdf">Samba-3 by Example</ulink>.
1110         </para>
1111
1112         </sect2>
1113
1114         <sect2>
1115         <title>Interdomain Trusts</title>
1116
1117         <para>
1118         Interdomain trust relationships form the primary mechanism by which users from one domain can be granted
1119         access rights and privileges in another domain.
1120         </para>
1121
1122         <para>
1123         To discover what trust relationships are in effect, execute this command:
1124 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom list</tertiary></indexterm>
1125 <screen>
1126 &rootprompt; net rpc trustdom list -Uroot%not24get
1127 Trusted domains list:
1128
1129 none
1130
1131 Trusting domains list:
1132
1133 none
1134 </screen>
1135         There are no interdomain trusts at this time; the following steps will create them.
1136         </para>
1137
1138         <para>
1139         It is necessary to create a trust account in the local domain. A domain controller in a second domain can
1140         create a trusted connection with this account. That means that the foreign domain is being trusted
1141         to access resources in the local domain. This command creates the local trust account:
1142 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom add</tertiary></indexterm>
1143 <screen>
1144 &rootprompt; net rpc trustdom add DAMNATION f00db4r -Uroot%not24get
1145 </screen>
1146         The account can be revealed by using the <command>pdbedit</command> as shown here:
1147 <screen>
1148 &rootprompt; pdbedit -Lw DAMNATION\$
1149 DAMNATION$:1016:9AC1F121DF897688AAD3B435B51404EE: \
1150 7F845808B91BB9F7FEF44B247D9DC9A6:[I         ]:LCT-428934B1:
1151 </screen>
1152         A trust account will always have an I in the field within the square brackets.
1153         </para>
1154
1155         <para>
1156         If the trusting domain is not capable of being reached, the following command will fail:
1157 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom list</tertiary></indexterm>
1158 <screen>
1159 &rootprompt; net rpc trustdom list -Uroot%not24get
1160 Trusted domains list:
1161
1162 none
1163
1164 Trusting domains list:
1165
1166 DAMNATION           S-1-5-21-1385457007-882775198-1210191635
1167 </screen>
1168         The above command executed successfully; a failure is indicated when the following response is obtained:
1169 <screen>
1170 net rpc trustdom list -Uroot%not24get
1171 Trusted domains list:
1172
1173 DAMNATION           S-1-5-21-1385457007-882775198-1210191635
1174
1175 Trusting domains list:
1176
1177 DAMNATION           domain controller is not responding
1178 </screen>
1179         </para>
1180
1181         <para>
1182         Where a trust account has been created on a foreign domain, Samba is able to establish the trust (connect with)
1183         the foreign account. In the process it creates a one-way trust to the resources on the remote domain. This
1184         command achieves the objective of joining the trust relationship:
1185 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom establish</tertiary></indexterm>
1186 <screen>
1187 &rootprompt; net rpc trustdom establish DAMNATION
1188 Password: xxxxxxx       == f00db4r
1189 Could not connect to server TRANSGRESSION
1190 Trust to domain DAMNATION established
1191 </screen>
1192         Validation of the two-way trust now established is possible as shown here:
1193 <screen>
1194 &rootprompt; net rpc trustdom list -Uroot%not24get
1195 Trusted domains list:
1196
1197 DAMNATION           S-1-5-21-1385457007-882775198-1210191635
1198
1199 Trusting domains list:
1200
1201 DAMNATION           S-1-5-21-1385457007-882775198-1210191635
1202 </screen>
1203         </para>
1204
1205         <para>
1206         Sometimes it is necessary to remove the ability for local users to access a foreign domain. The trusting
1207         connection can be revoked as shown here:
1208 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>trustdom revoke</tertiary></indexterm>
1209 <screen>
1210 &rootprompt; net rpc trustdom revoke DAMNATION -Uroot%not24get
1211 </screen>
1212         At other times it becomes necessary to remove the ability for users from a foreign domain to be able to
1213         access resources in the local domain. The command shown here will do that:
1214 <screen>
1215 &rootprompt; net rpc trustdom del DAMNATION -Uroot%not24get
1216 </screen>
1217
1218         </para>
1219
1220         </sect2>
1221
1222         </sect1>
1223
1224         <sect1>
1225         <title>Managing Security Identifiers (SIDS)</title>
1226
1227         <para>
1228 <indexterm><primary>security identifier</primary></indexterm>
1229 <indexterm><primary>SID</primary></indexterm>
1230 <indexterm><primary>desktop profiles</primary></indexterm>
1231 <indexterm><primary>user encoded</primary></indexterm>
1232 <indexterm><primary>group SID</primary></indexterm>
1233         The basic security identifier that is used by all Windows networking operations is the Windows security
1234         identifier (SID). All Windows network machines (servers and workstations), users, and groups are
1235         identified by their respective SID. All desktop profiles are also encoded with user and group SIDs that
1236         are specific to the SID of the domain to which the user belongs.
1237         </para>
1238
1239         <para>
1240 <indexterm><primary>machine SID</primary></indexterm>
1241 <indexterm><primary>domain SID</primary></indexterm>
1242 <indexterm><primary>SID</primary></indexterm>
1243 <indexterm><primary>rejoin</primary></indexterm>
1244         It is truly prudent to store the machine and/or domain SID in a file for safekeeping. Why? Because
1245         a change in hostname or in the domain (workgroup) name may result in a change in the SID. When you
1246         have the SID on hand, it is a simple matter to restore it. The alternative is to suffer the pain of
1247         having to recover user desktop profiles and perhaps rejoin all member machines to the domain.
1248         </para>
1249
1250         <para>
1251         First, do not forget to store the local SID in a file. It is a good idea to put this in the directory
1252         in which the &smb.conf; file is also stored. Here is a simple action to achieve this:
1253 <indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
1254 <screen>
1255 &rootprompt; net getlocalsid > /etc/samba/my-sid
1256 </screen>
1257         Good, there is now a safe copy of the local machine SID. On a PDC/BDC this is the domain SID also.
1258         </para>
1259
1260         <para>
1261         The following command reveals what the former one should have placed into the file called
1262         <filename>my-sid</filename>:
1263 <screen>
1264 &rootprompt; net getlocalsid
1265 SID for domain MERLIN is: S-1-5-21-726309263-4128913605-1168186429
1266 </screen>
1267         </para>
1268
1269         <para>
1270         If ever it becomes necessary to restore the SID that has been stored in the <filename>my-sid</filename>
1271         file, simply copy the SID (the string of characters that begins with <constant>S-1-5-21</constant>) to
1272         the command line shown here:
1273 <indexterm><primary>net</primary><secondary>setlocalsid</secondary></indexterm>
1274 <screen>
1275 &rootprompt; net setlocalsid S-1-5-21-1385457007-882775198-1210191635
1276 </screen>
1277         Restoration of a machine SID is a simple operation, but the absence of a backup copy can be very
1278         problematic.
1279         </para>
1280
1281         <para>
1282         The following operation is useful only for machines that are being configured as a PDC or a BDC.
1283         DMS and workstation clients should have their own machine SID to avoid
1284         any potential namespace collision. Here is the way that the BDC SID can be synchronized to that
1285         of the PDC (this is the default NT4 domain practice also):
1286 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>getsid</tertiary></indexterm>
1287 <screen>
1288 &rootprompt; net rpc getsid -S FRODO -Uroot%not24get
1289 Storing SID S-1-5-21-726309263-4128913605-1168186429 \
1290     for Domain MIDEARTH in secrets.tdb
1291 </screen>
1292         Usually it is not necessary to specify the target server (-S FRODO) or the administrator account
1293         credentials (-Uroot%not24get).
1294         </para>
1295
1296         </sect1>
1297
1298         <sect1>
1299         <title>Share Management</title>
1300
1301         <para>
1302         Share management is central to all file serving operations. Typical share operations include:
1303         </para>
1304
1305         <itemizedlist>
1306                 <listitem><para>Creation/change/deletion of shares</para></listitem>
1307                 <listitem><para>Setting/changing ACLs on shares</para></listitem>
1308                 <listitem><para>Moving shares from one server to another</para></listitem>
1309                 <listitem><para>Change of permissions of share contents</para></listitem>
1310         </itemizedlist>
1311
1312         <para>
1313         Each of these are dealt with here insofar as they involve the use of the <command>net</command>
1314         command. Operations outside of this command are covered elsewhere in this document.
1315         </para>
1316
1317         <sect2>
1318         <title>Creating, Editing, and Removing Shares</title>
1319
1320         <para>
1321         A share can be added using the <command>net rpc share</command> command capabilities.
1322         The target machine may be local or remote and is specified by the -S option. It must be noted
1323         that the addition and deletion of shares using this tool depends on the availability of a suitable
1324         interface script. The interface scripts Sambas <command>smbd</command> uses are called
1325         <smbconfoption name="add share script"/> and <smbconfoption name="delete share script"/>.
1326         A set of example scripts are provided in the Samba source code tarball in the directory
1327         <filename>~samba/examples/scripts</filename>.
1328         </para>
1329
1330         <para>
1331         The following steps demonstrate the use of the share management capabilities of the <command>net</command>
1332         utility. In the first step a share called <constant>Bulge</constant> is added. The sharepoint within the
1333         file system is the directory <filename>/data</filename>. The command that can be executed to perform the
1334         addition of this share is shown here:
1335 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share add</tertiary></indexterm>
1336 <screen>
1337 &rootprompt; net rpc share add Bulge=/data -S MERLIN -Uroot%not24get
1338 </screen>
1339         Validation is an important process, and by executing the command <command>net rpc share</command>
1340         with no other operators it is possible to obtain a listing of available shares, as shown here:
1341 <screen>
1342 &rootprompt; net rpc share -S MERLIN -Uroot%not24get
1343 profdata
1344 archive
1345 Bulge   &lt;--- This one was added
1346 print$
1347 netlogon
1348 profiles
1349 IPC$
1350 kyocera
1351 ADMIN$
1352 </screen>
1353         </para>
1354
1355         <para>
1356         Often it is desirable also to permit a share to be removed using a command-line tool.
1357         The following step permits the share that was previously added to be removed:
1358 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share delete</tertiary></indexterm>
1359 <screen>
1360 &rootprompt; net rpc share delete Bulge -S MERLIN -Uroot%not24get
1361 </screen>
1362         A simple validation shown here demonstrates that the share has been removed:
1363 <screen>
1364 &rootprompt; net rpc share -S MERLIN -Uroot%not24get
1365 profdata
1366 archive
1367 print$
1368 netlogon
1369 profiles
1370 IPC$
1371 ADMIN$
1372 kyocera
1373 </screen>
1374         </para>
1375
1376         </sect2>
1377
1378         <sect2>
1379         <title>Creating and Changing Share ACLs</title>
1380
1381         <para>
1382         At this time the <command>net</command> tool cannot be used to manage ACLs on Samba shares. In MS Windows
1383         language this is called Share Permissions.
1384         </para>
1385
1386         <para>
1387         It is possible to set ACLs on Samba shares using either the SRVTOOLS NT4 Domain Server Manager
1388         or using the Computer Management MMC snap-in. Neither is covered here,
1389         but see <link linkend="AccessControls"/>.
1390         </para>
1391
1392         </sect2>
1393
1394         <sect2>
1395         <title>Share, Directory, and File Migration</title>
1396
1397         <para>
1398 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
1399         Shares and files can be migrated in the same manner as user, machine, and group accounts.
1400         It is possible to preserve access control settings (ACLs) as well as security settings
1401         throughout the migration process. The <command>net rpc vampire</command> facility is used
1402         to migrate accounts from a Windows NT4 (or later) domain to a Samba server. This process
1403         preserves passwords and account security settings and is a precursor to the migration
1404         of shares and files.
1405         </para>
1406
1407         <para>
1408         The <command>net rpc share</command> command may be used to migrate shares, directories,
1409         files, printers, and all relevant data from a Windows server to a Samba server.
1410         </para>
1411
1412         <para>
1413         A set of command-line switches permit the creation of almost direct clones of Windows file
1414         servers. For example, when migrating a fileserver, file ACLs and DOS file attributes from
1415         the Windows server can be included in the migration process and will reappear, almost identically,
1416         on the Samba server when the migration has been completed.
1417         </para>
1418
1419         <para>
1420         The migration process can be completed only with the Samba server already being fully operational.
1421         The user and group accounts must be migrated before attempting to migrate data
1422         share, files, and printers. The migration of files and printer configurations involves the use
1423         of both SMB and MS DCE RPC services. The benefit of the manner in which the migration process has
1424         been implemented is that the possibility now exists to use a Samba server as a man-in-middle migration
1425         service that affects a transfer of data from one server to another. For example, if the Samba
1426         server is called MESSER, the source Windows NT4 server is called PEPPY, and the target Samba
1427         server is called GONZALES, the machine MESSER can be used to effect the migration of all data
1428         (files and shares) from PEPPY to GONZALES. If the target machine is not specified, the local
1429         server is assumed by default.
1430         </para>
1431
1432         <para>
1433         The success of server migration requires a firm understanding of the structure of the source
1434         server (or domain) as well as  the processes on which the migration is critically dependant.
1435         </para>
1436
1437         <para>
1438         There are two known limitations to the migration process:
1439         </para>
1440
1441         <orderedlist>
1442                 <listitem><para>
1443                 The <command>net</command> command requires that the user credentials provided exist on both
1444                 the migration source and the migration target.
1445                 </para></listitem>
1446
1447                 <listitem><para>
1448                 Printer settings may not be fully or may be incorrectly migrated. This might in particular happen
1449                 when migrating a Windows 2003 print server to Samba.
1450                 </para></listitem>
1451         </orderedlist>
1452
1453         <sect3>
1454         <title>Share Migration</title>
1455
1456         <para>
1457         The <command>net rpc share migrate</command> command operation permits the migration of plain
1458         share stanzas. A stanza contains the parameters within which a file or print share are defined.
1459         The use of this migration method will create share stanzas that have as parameters the file
1460         system directory path, an optional description, and simple security settings that permit write
1461         access to files. One of the first steps necessary following migration is to review the share
1462         stanzas to ensure that the settings are suitable for use.
1463         </para>
1464
1465         <para>
1466         The shares are created on the fly as part of the migration process. The <command>smbd</command>
1467         application does this by calling on the operating system to execute the script specified by the
1468         &smb.conf; parameter <parameter>add share command</parameter>.
1469         </para>
1470
1471         <para>
1472         There is a suitable example script for the <parameter>add share command</parameter> in the
1473         <filename>$SAMBA_SOURCES/examples/scripts</filename> directory. It should be noted that
1474         the account that is used to drive the migration must, of necessity, have appropriate file system
1475         access privileges and have the right to create shares and to set ACLs on them. Such rights are
1476         conferred by these rights: <parameter>SeAddUsersPrivilege</parameter> and <parameter>SeDiskOperatorPrivilege</parameter>.
1477         For more information regarding rights and privileges please refer to <link linkend="rights"/>.
1478         </para>
1479
1480         <para>
1481         The syntax of the share migration command is shown here:
1482 <screen>
1483 net rpc share MIGRATE SHARES &lt;share-name&gt; -S &lt;source&gt;
1484         [--destination=localhost] [--exclude=share1,share2] [-v]
1485 </screen>
1486         When the parameter &lt;share-name&gt; is omitted, all shares will be migrated. The potentially
1487         large list of available shares on the system that is being migrated can be limited using the
1488         <parameter>--exclude</parameter> switch. For example:
1489 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate</tertiary></indexterm>
1490 <screen>
1491 &rootprompt; net rpc share migrate shares myshare\
1492          -S win2k -U administrator%secret"
1493 </screen>
1494         This will migrate the share <constant>myshare</constant> from the server <constant>win2k</constant>
1495         to the Samba Server using the permissions that are tied to the account <constant>administrator</constant>
1496         with the password <constant>secret</constant>. The account that is used must be the same on both the
1497         migration source server and the target Samba server. The use of the <command>net rpc
1498         vampire</command>, prior to attempting the migration of shares, will ensure that accounts will be
1499         identical on both systems. One precaution worth taking before commencement of migration of shares is
1500         to validate that the migrated accounts (on the Samba server) have the needed rights and privileges.
1501         This can be done as shown here:
1502 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>right list accounts</tertiary></indexterm>
1503 <screen>
1504 &rootprompt; net rpc right list accounts -Uroot%not24get
1505 </screen>
1506         The steps taken so far perform only the migration of shares. Directories and directory contents
1507         are not migrated by the steps covered up to this point.
1508         </para>
1509
1510         </sect3>
1511
1512         <sect3>
1513         <title>File and Directory Migration</title>
1514
1515         <para>
1516         Everything covered to this point has been done in preparation for the migration of file and directory
1517         data. For many people preparation is potentially boring and the real excitement only begins when file
1518         data can be used. The next steps demonstrate the techniques that can be used to transfer (migrate)
1519         data files using the <command>net</command> command.
1520         </para>
1521
1522         <para>
1523         Transfer of files from one server to another has always been a challenge for MS Windows
1524         administrators because Windows NT and 200X servers do not include the tools needed. The
1525         <command>xcopy</command> is not capable of preserving file and directory ACLs. Microsoft does provide a
1526         utility that can copy ACLs (security settings) called <command>scopy</command>, but it is provided only
1527         as part of the Windows NT or 200X Server Resource Kit.
1528         </para>
1529
1530         <para>
1531         There are several tools, both commercial and freeware, that can be used from a Windows server to copy files
1532         and directories with full preservation of security settings. One of the best known of the free tools is
1533         called <command>robocopy</command>.
1534         </para>
1535
1536         <para>
1537         The <command>net</command> utility can be used to copy files and directories with full preservation of
1538         ACLs as well as DOS file attributes. Note that including ACLs makes sense only where the destination
1539         system will operate within the same security context as the source system. This applies both to a
1540         DMS and to domain controllers that result from a vampired domain.
1541         Before file and directory migration, all shares must already exist.
1542         </para>
1543
1544         <para>
1545         The syntax for the migration commands is shown here:
1546 <screen>
1547 net rpc share MIGRATE FILES &lt;share-name&gt; -S &lt;source&gt;
1548     [--destination=localhost] [--exclude=share1,share2]
1549     [--acls] [--attrs] [--timestamps] [-v]
1550 </screen>
1551         If the &lt;share-name&gt; parameter is omitted, all shares will be migrated. The potentially large
1552         list of shares on the source system can be restricted using the <parameter>--exclude</parameter> command
1553         switch.
1554         </para>
1555
1556         <para>
1557         Where it is necessary to preserve all file ACLs, the <parameter>--acls</parameter> switch should be added
1558         to the above command line. Original file timestamps can be preserved by specifying the
1559         <parameter>--timestamps</parameter> switch, and the DOS file attributes (i.e., hidden, archive, etc.) can
1560         be preserved by specifying the <parameter>--attrs</parameter> switch.
1561         </para>
1562
1563         <note><para>
1564         The ability to preserve ACLs depends on appropriate support for ACLs as well as the general file system
1565         semantics of the host operating system on the target server. A migration from one Windows file server to
1566         another will perfectly preserve all file attributes. Because of the difficulty of mapping Windows ACLs
1567         onto a POSIX ACLs-supporting system, there can be no perfect migration of Windows ACLs to a Samba server.
1568         </para></note>
1569
1570         <para>
1571         The ACLs that result on a Samba server will most probably not match the originating ACLs. Windows supports
1572         the possibility of files that are owned only by a group. Group-alone file ownership is not possible under
1573         UNIX/Linux. Errors in migrating group-owned files can be avoided by using the &smb.conf; file
1574         <smbconfoption name="force unknown acl user">yes</smbconfoption> parameter. This facility will
1575         automatically convert group-owned files into correctly user-owned files on the Samba server.
1576         </para>
1577
1578         <para>
1579         An example for migration of files from a machine called <constant>nt4box</constant> to the Samba server
1580         from which the process will be handled is shown here:
1581 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate files</tertiary></indexterm>
1582 <screen>
1583 &rootprompt; net rpc share migrate files -S nt4box --acls \
1584     --attrs -U administrator%secret
1585 </screen>
1586         </para>
1587
1588         <para>
1589         This command  will migrate all files and directories from all file shares on the Windows server called
1590         <constant>nt4box</constant> to the Samba server from which migration is initiated. Files that are group-owned
1591         will be owned by the user account <constant>administrator</constant>.
1592         </para>
1593
1594         </sect3>
1595
1596         <sect3>
1597         <title>Simultaneous Share and File Migration</title>
1598
1599         <para>
1600         The operating mode shown here is just a combination of the previous two. It first migrates
1601         share definitions and then all shared files and directories:
1602 <screen>
1603 net rpc share MIGRATE ALL &lt;share-name&gt; -S &lt;source&gt;
1604     [--exclude=share1, share2] [--acls] [--attrs] [--timestamps] [-v]
1605 </screen>
1606         </para>
1607
1608         <para>
1609         An example of simultaneous migration is shown here:
1610 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>share migrate all</tertiary></indexterm>
1611 <screen>
1612 &rootprompt; net rpc share migrate all -S w2k3server -U administrator%secret
1613 </screen>
1614         This will generate a complete server clone of the <parameter>w2k3server</parameter> server.
1615         </para>
1616
1617         </sect3>
1618
1619         </sect2>
1620
1621         <sect2>
1622         <title>Printer Migration</title>
1623
1624         <para>
1625         The installation of a new server, as with the migration to a new network environment, often is similar to
1626         building a house; progress is very rapid from the laying of foundations up to the stage at which
1627         the the house can be locked up, but the finishing off appears to take longer and longer as building
1628         approaches completion.
1629         </para>
1630
1631         <para>
1632         Printing needs vary greatly depending on the network environment and may be very simple or complex. If
1633         the need is very simple, the best solution to the implementation of printing support may well be to
1634         re-install everything from a clean slate instead of migrating older configurations. On the other hand,
1635         a complex network that is integrated with many international offices and a multiplexity of local branch
1636         offices, each of which form an inter-twined maze of printing possibilities, the ability to migrate all
1637         printer configurations is decidedly beneficial. To manually re-establish a complex printing network
1638         will take much time and frustration. Often it will not be possible to find driver files that are
1639         currently in use, necessitating the installation of newer drivers. Newer drivers often implement
1640         printing features that will necessitate a change in the printer usage. Additionally, with very complex
1641         printer configurations it becomes almost impossible to re-create the same environment &smbmdash; no matter
1642         how extensively it has been documented.
1643         </para>
1644
1645         <para>
1646         The migration of an existing printing architecture involves the following:
1647         </para>
1648
1649         <itemizedlist>
1650                 <listitem><para>Establishment of print queues.</para></listitem>
1651
1652                 <listitem><para>Installation of printer drivers (both for the print server and for Windows clients.</para></listitem>
1653
1654                 <listitem><para>Configuration of printing forms.</para></listitem>
1655
1656                 <listitem><para>Implementation of security settings.</para></listitem>
1657
1658                 <listitem><para>Configuration of printer settings.</para></listitem>
1659         </itemizedlist>
1660
1661         <para>
1662         The Samba <command>net</command> utility permits printer migration from one Windows print server
1663         to another. When this tool is used to migrate printers to a Samba server <command>smbd</command>,
1664         the application that receives the network requests to create the necessary services must call out
1665         to the operating system in order to create the underlying printers. The call-out is implemented
1666         by way of an interface script that can be specified by the &smb.conf; file parameter
1667         <smbconfoption id="add printer script"/>. This script is essential to the migration process.
1668         A suitable example script may be obtained from the <filename>$SAMBA_SOURCES/examples/scripts</filename>
1669         directory. Take note that this script must be customized to suit the operating system environment
1670         and may use its tools to create a print queue.
1671         </para>
1672
1673         <para>
1674         Each of the components listed above can be completed separately, or they can be completed as part of an
1675         automated operation. Many network administrators prefer to deal with migration issues in a manner that
1676         gives them the most control, particularly when things go wrong. The syntax for each operation is now
1677         briefly described.
1678         </para>
1679
1680         <para>
1681         Printer migration from a Windows print server (NT4 or 200x) is shown. This instruction causes the
1682         printer share to be created together with the underlying print queue:
1683 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate printers</tertiary></indexterm>
1684 <screen>
1685 net rpc printer MIGRATE PRINTERS [printer] [misc. options] [targets]
1686 </screen>
1687         Printer drivers can be migrated from the Windows print server to the Samba server using this
1688         command-line instruction:
1689 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate drivers</tertiary></indexterm>
1690 <screen>
1691 net rpc printer MIGRATE DRIVERS [printer] [misc. options] [targets]
1692 </screen>
1693         Printer forms can be migrated with the following operation:
1694 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate forms</tertiary></indexterm>
1695 <screen>
1696 net rpc printer MIGRATE FORMS [printer] [misc. options] [targets]
1697 </screen>
1698         Printer security settings (ACLs) can be migrated from the Windows server to the Samba server using this command:
1699 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate security</tertiary></indexterm>
1700 <screen>
1701 net rpc printer MIGRATE SECURITY [printer] [misc. options] [targets]
1702 </screen>
1703         Printer configuration settings include factors such as paper size and default paper orientation.
1704         These can be migrated from the Windows print server to the Samba server with this command:
1705 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>printer migrate settings</tertiary></indexterm>
1706 <screen>
1707 net rpc printer MIGRATE SETTINGS [printer] [misc. options] [targets]
1708 </screen>
1709         </para>
1710
1711         <para>
1712         Migration of printers including the above-mentioned sets of information may be completed
1713         with a single command using this syntax:
1714 <screen>
1715 net rpc printer MIGRATE ALL [printer] [misc. options] [targets]
1716 </screen>
1717         </para>
1718
1719         </sect2>
1720
1721         </sect1>
1722
1723         <sect1>
1724         <title>Controlling Open Files</title>
1725
1726         <para>
1727         The man page documents the <command>net file</command> function suite, which provides the tools to
1728         close open files using either RAP or RPC function calls. Please refer to the man page for specific
1729         usage information.
1730         </para>
1731
1732         </sect1>
1733
1734         <sect1>
1735         <title>Session and Connection Management</title>
1736
1737         <para>
1738         The session management interface of the <command>net session</command> command uses the old RAP
1739         method to obtain the list of connections to the Samba server, as shown here:
1740 <indexterm><primary>net</primary><secondary>rap</secondary><tertiary>session</tertiary></indexterm>
1741 <screen>
1742 &rootprompt; net rap session -S MERLIN -Uroot%not24get
1743 Computer             User name            Client Type        Opens Idle time
1744 ------------------------------------------------------------------------------
1745 \\merlin             root                 Unknown Client         0 00:00:00
1746 \\marvel             jht                  Unknown Client         0 00:00:00
1747 \\maggot             jht                  Unknown Client         0 00:00:00
1748 \\marvel             jht                  Unknown Client         0 00:00:00
1749 </screen>
1750         </para>
1751
1752         <para>
1753         A session can be closed by executing a command as shown here:
1754 <screen>
1755 &rootprompt; net rap session close marvel -Uroot%not24get
1756 </screen>
1757         </para>
1758
1759         </sect1>
1760
1761         <sect1>
1762         <title>Printers and ADS</title>
1763
1764         <para>
1765         When Samba-3 is used within an MS Windows ADS environment, printers shared via Samba will not be browseable
1766         until they have been published to the ADS domain. Information regarding published printers may be obtained
1767         from the ADS server by executing the <command>net ads print info</command> command following this syntax:
1768 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer info</tertiary></indexterm>
1769 <screen>
1770 net ads printer info &lt;printer_name&gt; &lt;server_name&gt; -Uadministrator%secret
1771 </screen>
1772         If the asterisk (*) is used in place of the printer_name argument, a list of all printers will be
1773         returned.
1774         </para>
1775
1776         <para>
1777         To publish (make available) a printer to ADS, execute the following command:
1778 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer publish</tertiary></indexterm>
1779 <screen>
1780 net ads printer publish &lt;printer_name&gt; -Uadministrator%secret
1781 </screen>
1782         This publishes a printer from the local Samba server to ADS.
1783         </para>
1784
1785         <para>
1786         Removal of a Samba printer from ADS is achieved by executing this command:
1787 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer remove</tertiary></indexterm>
1788 <screen>
1789 net ads printer remove &lt;printer_name&gt; -Uadministrator%secret
1790 </screen>
1791         </para>
1792
1793         <para>
1794         A generic search (query) can also be made to locate a printer across the entire ADS domain by executing:
1795 <indexterm><primary>net</primary><secondary>ads</secondary><tertiary>printer search</tertiary></indexterm>
1796 <screen>
1797 net ads printer search &lt;printer_name&gt; -Uadministrator%secret
1798 </screen>
1799         </para>
1800
1801         </sect1>
1802
1803         <sect1>
1804         <title>Manipulating the Samba Cache</title>
1805
1806         <para>
1807         Please refer to the <command>net</command> command man page for information regarding cache management.
1808         </para>
1809
1810         </sect1>
1811
1812         <sect1 id="netmisc1">
1813         <title>Other Miscellaneous Operations</title>
1814
1815         <para>
1816         The following command is useful for obtaining basic statistics regarding a Samba domain. This command does
1817         not work with current Windows XP Professional clients.
1818 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>info</tertiary></indexterm>
1819 <screen>
1820 &rootprompt; net rpc info
1821 Domain Name: RAPIDFLY
1822 Domain SID: S-1-5-21-399034208-633907489-3292421255
1823 Sequence number: 1116312355
1824 Num users: 720
1825 Num domain groups: 27
1826 Num local groups: 6
1827 </screen>
1828         </para>
1829
1830         <para>
1831         Another useful tool is the <command>net time</command> tool set. This tool may be used to query the
1832         current time on the target server as shown here:
1833 <indexterm><primary>net</primary><secondary>time</secondary></indexterm>
1834 <screen>
1835 &rootprompt; net time -S SAURON
1836 Tue May 17 00:50:43 2005
1837 </screen>
1838         In the event that it is the intent to pass the time information obtained to the UNIX
1839         <command>/bin/time</command>, it is a good idea to obtain the time from the target server in a format
1840         that is ready to be passed through. This may be done by executing:
1841 <indexterm><primary>net</primary><secondary>time</secondary><tertiary>system</tertiary></indexterm>
1842 <screen>
1843 &rootprompt; net time system -S FRODO
1844 051700532005.16
1845 </screen>
1846         The time can be set on a target server by executing:
1847 <indexterm><primary>net</primary><secondary>time</secondary><tertiary>set</tertiary></indexterm>
1848 <screen>
1849 &rootprompt; net time set -S MAGGOT -U Administrator%not24get
1850 Tue May 17 00:55:30 MDT 2005
1851 </screen>
1852         It is possible to obtain the time zone of a server by executing the following command against it:
1853 <indexterm><primary>net</primary><secondary>time</secondary><tertiary>zone</tertiary></indexterm>
1854 <screen>
1855 &rootprompt; net time zone -S SAURON
1856 -0600
1857 </screen>
1858         </para>
1859
1860         </sect1>
1861
1862 </chapter>