From f23c19359fa9702fead4a5aecb0dc0eaaf9d0e5f Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 19 Mar 2003 20:08:30 +0000 Subject: Add documentation on new modules system (This used to be commit f0f454129a5a57e50391397f45d7cf4d58648d45) --- docs/docbook/devdoc/dev-doc.sgml | 2 + docs/docbook/devdoc/modules.sgml | 147 ++++++++++++++++++++++++++++++++++++ docs/docbook/devdoc/rpc_plugin.sgml | 13 +++- 3 files changed, 159 insertions(+), 3 deletions(-) create mode 100644 docs/docbook/devdoc/modules.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml index b5c934b1c8..f10fe72414 100644 --- a/docs/docbook/devdoc/dev-doc.sgml +++ b/docs/docbook/devdoc/dev-doc.sgml @@ -13,6 +13,7 @@ + ]> @@ -67,6 +68,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt diff --git a/docs/docbook/devdoc/modules.sgml b/docs/docbook/devdoc/modules.sgml new file mode 100644 index 0000000000..098044ddfe --- /dev/null +++ b/docs/docbook/devdoc/modules.sgml @@ -0,0 +1,147 @@ + + + + JelmerVernooij + + Samba Team +
jelmer@samba.org
+ + + 19 March 2003 + + +Modules + + +Advantages + + +The new modules system has the following advantages: + + + +Transparent loading of static and shared modules (no need +for a subsystem to know about modules) +Simple selection between shared and static modules at configure time +"preload modules" option for increasing performance for stable modules +No nasty #define stuff anymore +All backends are available as plugin now (including pdb_ldap and pdb_tdb) + + + + +Loading modules + + +Some subsystems in samba use different backends. These backends can be +either statically linked in to samba or available as a plugin. A subsystem +should have a function that allows a module to register itself. For example, +the passdb subsystem has: + + + +BOOL smb_register_passdb(const char *name, pdb_init_function init, int version); + + + +This function will be called by the initialisation function of the module to +register itself. + + + +Static modules + + +The modules system compiles a list of initialisation functions for the +static modules of each subsystem. This is a define. For example, +it is here currently (from include/config.h): + + + +/* Static init functions */ +#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();} + + + +These functions should be called before the subsystem is used. That can be +done either from the executable that will be using the subsystem ( +static_init_rpc is called from the main() function of smbd), or +from the subsystem itself when it's first used (like passdb's +lazy_initialise_passdb does). + + + + + +Shared modules + + +If a subsystem needs a certain backend, it should check if it has +already been registered. If the backend hasn't been registered already, +the subsystem should call smb_probe_module(char *subsystem, char *backend). +This function tries to load the correct module from a certain path +($LIBDIR/subsystem/backend.so). If the first character in 'backend' +is a slash, smb_probe_module() tries to load the module from the +absolute path specified in 'backend'. + + +After smb_probe_module() has been executed, the subsystem +should check again if the module has been registered. + + + + + + +Writing modules + + +Each module has an initialisation function. For modules that are +included with samba this name is 'subsystem_backend_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'module_init'. +The prototype for this function is: + + + +int module_init(void); + + +This function should call one or more +registration The function should return non-zero on success and zero on +failure. + +For example, pdb_ldap_init() contains: + + +int pdb_ldap_init(void) +{ + smb_register_passdb("ldapsam", pdb_init_ldapsam, PASSDB_INTERFACE_VERSION); + smb_register_passdb("ldapsam_nua", pdb_init_ldapsam_nua, PASSDB_INTERFACE_VERSION); + return TRUE; +} + + + +Static/Shared selection in configure.in + + +Some macros in configure.in generate the various defines and substs that +are necessary for the system to work correct. All modules that should +be built by default have to be added to the variable 'default_modules'. +For example, if ldap is found, pdb_ldap is added to this variable. + + + +On the bottom of configure.in, SMB_MODULE() should be called +for each module and SMB_SUBSYSTEM() for each subsystem. + + +Syntax: + + +SMB_MODULE($MODULE_subsystem_backend, subsystem_backend, object files, plugin name, subsystem name) +SMB_SUBSYSTEM(subsystem) + + + + + diff --git a/docs/docbook/devdoc/rpc_plugin.sgml b/docs/docbook/devdoc/rpc_plugin.sgml index 21582a011d..c83742a247 100644 --- a/docs/docbook/devdoc/rpc_plugin.sgml +++ b/docs/docbook/devdoc/rpc_plugin.sgml @@ -7,6 +7,13 @@
aliguor@us.ibm.com
+ + JelmerVernooij + + Samba Team +
jelmer@samba.org
+ + January 2003 @@ -33,12 +40,12 @@ When an RPC call is sent to smbd, smbd tries to load a shared library by the name librpc_<pipename>.so to handle the call if it doesn't know how to handle the call internally. For instance, LSA calls are handled by librpc_lsass.so.. -These shared libraries should be located in the <sambaroot>/lib/rpc. smbd then attempts to call the rpc_pipe_init function within -the shared library. +These shared libraries should be located in the <sambaroot>/lib/rpc. smbd then attempts to call the init_module function within +the shared library. Check the chapter on modules for more information. -In the rpc_pipe_init function, the library should call +In the init_module function, the library should call rpc_pipe_register_commands(). This function takes the following arguments: -- cgit From a63fa73d7327e88ec9c08b63a8ff4980ec043e52 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 19 Mar 2003 20:16:43 +0000 Subject: Fix uncompleted sentence (This used to be commit a14b7fcd493b89e6ea6bcc889a2d2f24fc72a5fc) --- docs/docbook/devdoc/modules.sgml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/modules.sgml b/docs/docbook/devdoc/modules.sgml index 098044ddfe..de43813410 100644 --- a/docs/docbook/devdoc/modules.sgml +++ b/docs/docbook/devdoc/modules.sgml @@ -97,8 +97,8 @@ should check again if the module has been registered. Each module has an initialisation function. For modules that are -included with samba this name is 'subsystem_backend_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'module_init'. -The prototype for this function is: +included with samba this name is 'subsystem_backend_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'module_init'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() module_init()). +The prototype for these functions is: @@ -106,7 +106,7 @@ int module_init(void); This function should call one or more -registration The function should return non-zero on success and zero on +registration functions. The function should return non-zero on success and zero on failure. For example, pdb_ldap_init() contains: -- cgit From 7178e11a49177bc35a6637dae0156748ff01d799 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 19 Mar 2003 20:19:47 +0000 Subject: It's init_module(), not module_init() as metze pointed out. I really thought I check this well enough :-/ (This used to be commit 730e2a093152c406923bd9e28339781564b0afac) --- docs/docbook/devdoc/modules.sgml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/modules.sgml b/docs/docbook/devdoc/modules.sgml index de43813410..99cba605bd 100644 --- a/docs/docbook/devdoc/modules.sgml +++ b/docs/docbook/devdoc/modules.sgml @@ -97,12 +97,12 @@ should check again if the module has been registered. Each module has an initialisation function. For modules that are -included with samba this name is 'subsystem_backend_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'module_init'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() module_init()). +included with samba this name is 'subsystem_backend_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()). The prototype for these functions is: -int module_init(void); +int init_module(void); This function should call one or more -- cgit From a666912f7bcc9945c2eed29701cba90b7579796e Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 19 Mar 2003 20:47:35 +0000 Subject: Don't generate a Samba-Developers-Guide.{ps,txt} with the contents of the Samba HOWTO collection (This used to be commit 4ce0e931ab098768e5a33c0062267176104485b2) --- docs/docbook/Makefile.in | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/Makefile.in b/docs/docbook/Makefile.in index ae24606caf..d52bcac8f9 100644 --- a/docs/docbook/Makefile.in +++ b/docs/docbook/Makefile.in @@ -83,9 +83,9 @@ $(TXTDIR)/Samba-HOWTO-Collection.txt: $(PROJDOC)/samba-doc.sgml $(DOCBOOK2TXT) -o . $< mv ./samba-doc.txt $@ -$(TXTDIR)/Samba-Developers-Guide.txt: $(PROJDOC)/samba-doc.sgml +$(TXTDIR)/Samba-Developers-Guide.txt: $(DEVDOC)/dev-doc.sgml $(DOCBOOK2TXT) -o . $< - mv ./samba-doc.txt $@ + mv ./dev-doc.txt $@ # PostScript @@ -93,9 +93,9 @@ $(PSDIR)/Samba-HOWTO-Collection.ps: $(PROJDOC)/samba-doc.sgml $(DOCBOOK2PS) -o . $< mv ./samba-doc.ps $@ -$(PSDIR)/Samba-Developers-Guide.ps: $(PROJDOC)/samba-doc.sgml +$(PSDIR)/Samba-Developers-Guide.ps: $(DEVDOC)/dev-doc.sgml $(DOCBOOK2PS) -o . $< - mv ./samba-doc.ps $@ + mv ./dev-doc.ps $@ # Adobe PDF files -- cgit From bff325e15e1dfaba7272212eb7c83fd271b90a47 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 20 Mar 2003 10:52:12 +0000 Subject: Update wbinfo.1 for 3.0 (This used to be commit c057c6594e8c44993c01d6bb3a8d0916a2adcd24) --- docs/docbook/manpages/wbinfo.1.sgml | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/wbinfo.1.sgml b/docs/docbook/manpages/wbinfo.1.sgml index 5003c847a4..3c7ae11e2c 100644 --- a/docs/docbook/manpages/wbinfo.1.sgml +++ b/docs/docbook/manpages/wbinfo.1.sgml @@ -17,8 +17,8 @@ wbinfo -u -g - -i ip -N netbios-name + -I ip -n name -s sid -U uid @@ -27,9 +27,11 @@ -Y sid -t -m + --sequence -r user -a user%password -A user%password + --get-auth-user -p @@ -176,6 +178,11 @@ + + --sequence + Show sequence numbers of + all known domains + -r username @@ -203,6 +210,23 @@ Windows 2000 servers only). + + + --get-auth-user + Print username and password used by winbindd + during session setup to a domain controller. Username + and password can be set using '-A'. Only available for + root. + + + + -p + Check whether winbindd is still alive. + Prints out either 'succeeded' or 'failed'. + + + + -- cgit From 573746991469eb41af71145301802fe06ab75f9e Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 20 Mar 2003 11:09:36 +0000 Subject: Update swat docs for 3.0 (This used to be commit 06c7a16b2d2040c0932eb663076cecb6d2cd3cdf) --- docs/docbook/manpages/swat.8.sgml | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/swat.8.sgml b/docs/docbook/manpages/swat.8.sgml index 9c4daad6d0..a13ba9ff6c 100644 --- a/docs/docbook/manpages/swat.8.sgml +++ b/docs/docbook/manpages/swat.8.sgml @@ -66,6 +66,11 @@ WARNING: Do NOT enable this option on a production server. + + + -V + Print version number of samba suite + @@ -74,6 +79,12 @@ INSTALLATION + Swat is included as binary package with most distributions. The + package manager in this case takes care of the installation and + configuration. This section is only for those who have compiled + swat from scratch. + + After you compile SWAT you need to run make install to install the swat binary and the various help files and images. A default install would put @@ -97,7 +108,7 @@ swat 901/tcp - Note for NIS/YP users - you may need to rebuild the + Note for NIS/YP and LDAP users - you may need to rebuild the NIS service maps rather than alter your local /etc/services file. @@ -121,17 +132,19 @@ - - Launching - To launch SWAT just run your favorite web browser and - point it at "http://localhost:901/". + - Note that you can attach to SWAT from any IP connected - machine but connecting from a remote machine leaves your - connection open to password sniffing as passwords will be sent - in the clear over the wire. - + + LAUNCHING + + To launch SWAT just run your favorite web browser and + point it at "http://localhost:901/". + + Note that you can attach to SWAT from any IP connected + machine but connecting from a remote machine leaves your + connection open to password sniffing as passwords will be sent + in the clear over the wire. @@ -180,7 +193,7 @@ VERSION - This man page is correct for version 2.2 of the Samba suite. + This man page is correct for version 3.0 of the Samba suite. -- cgit From 7477c65048889133d8b9c257fead9e4a9da8f8db Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 20 Mar 2003 12:08:42 +0000 Subject: Update smbcacls.1 for 3.0 (This used to be commit 0ab40fac3a45b1f72b8bd53a48fc39dd46c69086) --- docs/docbook/manpages/smbcacls.1.sgml | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smbcacls.1.sgml b/docs/docbook/manpages/smbcacls.1.sgml index 5e0e6c80e9..4482019669 100644 --- a/docs/docbook/manpages/smbcacls.1.sgml +++ b/docs/docbook/manpages/smbcacls.1.sgml @@ -17,15 +17,17 @@ smbcacls //server/share filename - -U username - -A acls - -M acls -D acls + -M acls + -A acls -S acls -C name -G name -n + -t + -U username -h + -d @@ -34,7 +36,7 @@ This tool is part of the Samba 7 suite. - + The smbcacls program manipulates NT Access Control Lists (ACLs) on SMB file shares. @@ -131,8 +133,14 @@ and masks to a readable string format. - - + + -t + + Don't actually do anything, only validate the correctness of + the arguments. + + + -h Print usage information on the smbcacls @@ -232,7 +240,7 @@ ACL:<sid or name>:<type>/<flags>/<mask> VERSION - This man page is correct for version 2.2 of the Samba suite. + This man page is correct for version 3.0 of the Samba suite. -- cgit From 055094c46088188a5f1e0c7f3cb784ba782951a4 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 23 Mar 2003 00:12:37 +0000 Subject: Also move -V to -C in docs (This used to be commit 33097cc6610380c373c121380e51d5656955971b) --- docs/docbook/manpages/pdbedit.8.sgml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/pdbedit.8.sgml b/docs/docbook/manpages/pdbedit.8.sgml index e6231bfa8c..973b772374 100644 --- a/docs/docbook/manpages/pdbedit.8.sgml +++ b/docs/docbook/manpages/pdbedit.8.sgml @@ -35,7 +35,7 @@ -d debuglevel -s configfile -P account-policy - -V value + -C value @@ -287,13 +287,13 @@ account policy value for bad lockout attempt is 0 - -V account-policy-value + -C account-policy-value Sets an account policy to a specified value. This option may only be used in conjunction with the -P option. - Example: pdbedit -P "bad lockout attempt" -V 3 + Example: pdbedit -P "bad lockout attempt" -C 3 account policy value for bad lockout attempt was 0 account policy value for bad lockout attempt is now 3 -- cgit From 440709a9d86f2630c57d4f12b92b5f64ded9bf7a Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 23 Mar 2003 00:26:09 +0000 Subject: Add minimum man page (This used to be commit 8597b8cb952713239aa510ef84e295a8bc8271c6) --- docs/docbook/manpages/profiles.1.sgml | 88 +++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/docbook/manpages/profiles.1.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/profiles.1.sgml b/docs/docbook/manpages/profiles.1.sgml new file mode 100644 index 0000000000..0d18c42c82 --- /dev/null +++ b/docs/docbook/manpages/profiles.1.sgml @@ -0,0 +1,88 @@ + %globalentities; +]> + + + + profiles + 1 + + + + + profiles + A utility to report and change SIDs in registry files + + + + + + profiles + -v + -c SID + -n SID + file + + + + + DESCRIPTION + + This tool is part of the Samba + 7 suite. + + profiles is a utility that + reports and changes SIDs in windows registry files. It currently only + supports NT. + + + + + + OPTIONS + + + + file + Registry file to view or edit. + + + + + -v,--verbose + Increases verbosity of messages. + + + + + + + -c SID1 -n SID2 + Change all occurences of SID1 in file by SID2. + + + + &stdarg.help; + + + + + + VERSION + + This man page is correct for version 3.0 of the Samba + suite. + + + + AUTHOR + + The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed. + + The profiles man page was written by Jelmer Vernooij. + + + -- cgit From 933b4d0d1b5a6521fea2ccad1e0ff5cad82737db Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 23 Mar 2003 09:04:25 +0000 Subject: This adds 'ldap delete dn' as the recommended parameter for the 'ldap del only sam attr' functionality. So we are compatiple to the current SuSE patches as well as to TNG... ;-) Volker (This used to be commit 353309e2a3bc27e918bd0a6cf22833d57895fbc8) --- docs/docbook/manpages/smb.conf.5.sgml | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smb.conf.5.sgml b/docs/docbook/manpages/smb.conf.5.sgml index 7aaa189578..0f5e751a64 100644 --- a/docs/docbook/manpages/smb.conf.5.sgml +++ b/docs/docbook/manpages/smb.conf.5.sgml @@ -656,6 +656,7 @@ alias|alias|alias|alias... large readwrite ldap admin dn + ldap delete dn ldap del only sam attr ldap filter ldap port @@ -3437,13 +3438,22 @@ df $1 | tail -1 | awk '{print $2" "$4}' - ldap del only sam attr (G) + ldap del only sam attr (G) This parameter specifies whether a delete - operation in the ldapsam deletes only the Samba-specific - attributes or the complete LDAP entry. + operation in the ldapsam deletes the complete entry or only the attributes + specific to Samba. - Default : ldap del only sam attr = yes + Default : ldap delete dn = no + + + + + + ldap del only sam attr (G) + Inverted synonym for + ldap delete dn. + -- cgit From cf4f074b94052360a3e9c7d1e3d91ba8a3531212 Mon Sep 17 00:00:00 2001 From: Volker Lendecke Date: Sun, 23 Mar 2003 11:49:24 +0000 Subject: This does two things: * pdbedit -i -e sets all SAM_ACCOUNT elements to CHANGED to satisfy the new pdb_ldap.c handling * pdbedit -g transfers group mappings. I made this separate from the user database, as current installations have to live with a split backend. So, if you are running 3_0 alphas with LDAP as a backend and upgrade to the next 3_0 alpha, you should call pdbedit -i tdbsam -e ldapsam -g to transfer your group mapping database to LDAP. You certainly have to have all your groups as posixGroup objects in LDAP and adapt the LDAP schema before this call. Volker (This used to be commit 6d3faeaef6c77e389d39b6d4660ffea13e7f25f2) --- docs/docbook/manpages/pdbedit.8.sgml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/pdbedit.8.sgml b/docs/docbook/manpages/pdbedit.8.sgml index 973b772374..113f23f9c4 100644 --- a/docs/docbook/manpages/pdbedit.8.sgml +++ b/docs/docbook/manpages/pdbedit.8.sgml @@ -31,7 +31,9 @@ -x -i passdb-backend -e passdb-backend + -g -b passdb-backend + -g -d debuglevel -s configfile -P account-policy @@ -263,6 +265,30 @@ retype new password + + -g + If you specify -g, + then -i in-backend -e out-backend + applies to the group mapping instead of the user database. + + This option will ease migration from one passdb backend to + another and will ease backing up. + + + + + + -g + If you specify -g, + then -i in-backend -e out-backend + applies to the group mapping instead of the user database. + + This option will ease migration from one passdb backend to + another and will ease backing up. + + + + -b passdb-backend Use a different default passdb backend. -- cgit From 93f7be0b3aa75ebe63d8f6e7c9122866fa703462 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 23 Mar 2003 16:26:53 +0000 Subject: Document Tim's smbtree program (This used to be commit aa528bf0f2c3286a6f78c1a36e48c6ff15a85457) --- docs/docbook/manpages/smbtree.1.sgml | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/docbook/manpages/smbtree.1.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smbtree.1.sgml b/docs/docbook/manpages/smbtree.1.sgml new file mode 100644 index 0000000000..ce664908bc --- /dev/null +++ b/docs/docbook/manpages/smbtree.1.sgml @@ -0,0 +1,91 @@ + %globalentities; +]> + + + + smbtree + 1 + + + + + smbtree + A text based smb network browser + + + + + + smbtree + -b + -D + -S + + + + + DESCRIPTION + + This tool is part of the Samba + 7 suite. + + smbtree is a smb browser program + in text mode. It is similar to the "Network Neighborhood" found + on Windows computers. It prints a tree with all + the known domains, the servers in those domains and + the shares on the servers. + + + + + + OPTIONS + + + + -b + Query network nodes by sending requests + as broadcasts instead of querying the (domain) master browser. + + + + + -D + Only print a list of all + the domains known on broadcast or by the + master browser + + + + -S + Only print a list of + all the domains and servers responding on broadcast or + known by the master browser. + + + + &stdarg.help; + + + + + + VERSION + + This man page is correct for version 3.0 of the Samba + suite. + + + + AUTHOR + + The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed. + + The smbtree man page was written by Jelmer Vernooij. + + + -- cgit From 4f70a8f6587e6d1c0cb9e5530197733ea48d7719 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sun, 23 Mar 2003 16:27:31 +0000 Subject: Build the profiles.1 and smbtree.1 manpages (This used to be commit 5bf945d86927e09cbb665e6fb59111b6bdc60fd4) --- docs/docbook/Makefile.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/docbook') diff --git a/docs/docbook/Makefile.in b/docs/docbook/Makefile.in index d52bcac8f9..66266196d5 100644 --- a/docs/docbook/Makefile.in +++ b/docs/docbook/Makefile.in @@ -21,7 +21,8 @@ MANPAGES_NAMES=findsmb.1 smbclient.1 \ smbpasswd.8 testprns.1 \ smb.conf.5 wbinfo.1 pdbedit.8 \ smbcacls.1 smbsh.1 winbindd.8 \ - smbgroupedit.8 vfstest.1 + smbgroupedit.8 vfstest.1 \ + profiles.1 smbtree.1 ## This part contains only rules. You shouldn't need to change it ## if you are adding docs -- cgit From e5ae6d548ff3c11a1be5ce3509da278b09994a34 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Mon, 24 Mar 2003 14:14:10 +0000 Subject: Document common arguments with entities (This used to be commit adafcbb9af4a22db0fefb70966564d8591b5baed) --- docs/docbook/global.ent | 164 ++++++++++++++++++++++++++++++-- docs/docbook/manpages/nmbd.8.sgml | 98 ++----------------- docs/docbook/manpages/nmblookup.1.sgml | 54 ++--------- docs/docbook/manpages/pdbedit.8.sgml | 3 +- docs/docbook/manpages/profiles.1.sgml | 1 + docs/docbook/manpages/rpcclient.1.sgml | 87 +---------------- docs/docbook/manpages/smbcacls.1.sgml | 7 +- docs/docbook/manpages/smbclient.1.sgml | 167 ++------------------------------- docs/docbook/manpages/smbd.8.sgml | 64 +------------ docs/docbook/manpages/smbstatus.1.sgml | 26 ++--- docs/docbook/manpages/smbtree.1.sgml | 2 + docs/docbook/manpages/swat.8.sgml | 11 ++- docs/docbook/manpages/testparm.1.sgml | 14 ++- docs/docbook/manpages/vfstest.1.sgml | 3 +- docs/docbook/manpages/wbinfo.1.sgml | 6 +- docs/docbook/manpages/winbindd.8.sgml | 20 ++-- 16 files changed, 220 insertions(+), 507 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/global.ent b/docs/docbook/global.ent index 46745c2773..a3022ecfaa 100644 --- a/docs/docbook/global.ent +++ b/docs/docbook/global.ent @@ -31,7 +31,7 @@ - -d|--debug=debuglevel @@ -59,13 +59,6 @@ level parameter in the '> - --h|--help -Print a summary of command line options. - -'> - -s <configuration file> @@ -82,7 +75,160 @@ compile time. --v +-V Prints the version number for smbd. '> + + +-l|--logfile=logbasename +File name for log/debug files. The extension +".client" will be appended. The log file is +never removed by the client. + +'> + + + + +-n <primary NetBIOS name> +This option allows you to override +the NetBIOS name that Samba uses for itself. This is identical +to setting the NetBIOS +name parameter in the smb.conf +5 file. However, a command +line setting will take precedence over settings in +smb.conf +5. +'> + + + + +-i <scope> +This specifies a NetBIOS scope that +nmblookup will use to communicate with when +generating NetBIOS names. For details on the use of NetBIOS +scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes are +very rarely used, only set this parameter +if you are the system administrator in charge of all the +NetBIOS systems you communicate with. +'> + + +-W|--workgroup=domain +Set the SMB domain of the username. This +overrides the default domain which is the domain defined in +smb.conf. If the domain specified is the same as the servers +NetBIOS name, it causes the client to log on using the servers local +SAM (as opposed to the Domain SAM). +'> + + +-O socket options +TCP socket options to set on the client +socket. See the socket options parameter in +the smb.conf +5 manual page for the list of valid +options. + +'> + + + + +-N +If specified, this parameter suppresses the normal +password prompt from the client to the user. This is useful when +accessing a service that does not require a password. + +Unless a password is specified on the command line or +this parameter is specified, the client will request a +password. +'> + + +-U|--user=username[&%;password] +Sets the SMB username or username and password. + +If &%;password is not specified, the user will be prompted. The +client will first check the USER environment variable, then the +LOGNAME variable and if either exists, the +string is uppercased. If these environmental variables are not +found, the username GUEST is used. + +A third option is to use a credentials file which +contains the plaintext of the username and password. This +option is mainly provided for scripts where the admin does not +wish to pass the credentials on the command line or via environment +variables. If this method is used, make certain that the permissions +on the file restrict access from unwanted users. See the +-A for more details. + +Be cautious about including passwords in scripts. Also, on +many systems the command line of a running process may be seen +via the ps command. To be safe always allow +rpcclient to prompt for a password and type +it in directly. + +'> + + +-A|--authfile=filename +This option allows +you to specify a file from which to read the username and +password used in the connection. The format of the file is + + + +username = <value> +password = <value> +domain = <value> + + +Make certain that the permissions on the file restrict +access from unwanted users. +'> + + +-k + +Try to authenticate with kerberos. Only useful in +an Active Directory environment. + + +'> + + + +-h|--help +Print a summary of command line options. + +'> + + diff --git a/docs/docbook/manpages/nmbd.8.sgml b/docs/docbook/manpages/nmbd.8.sgml index 6c7ecce4e9..5f359ff099 100644 --- a/docs/docbook/manpages/nmbd.8.sgml +++ b/docs/docbook/manpages/nmbd.8.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -111,13 +113,6 @@ than a file. - - -a - If this parameter is specified, each new - connection will append log messages to the log file. - This is the default. - - -i If this parameter is specified it causes the @@ -129,19 +124,7 @@ given. - - -o - If this parameter is specified, the - log files will be overwritten when opened. By default, - smbd will append entries to the log - files. - - - - -h - Prints the help information (usage) - for nmbd. - + &stdarg.help; -H <filename> @@ -165,66 +148,9 @@ 5 man page for details on the contents of this file. - - -V - Prints the version number for - nmbd. - + &popt.common.samba; + &popt.common.connection; - - -d <debug level> - debuglevel is an integer - from 0 to 10. The default value if this parameter is - not specified is zero. - - The higher this value, the more detail will - be logged to the log files about the activities of the - server. At level 0, only critical errors and serious - warnings will be logged. Level 1 is a reasonable level for - day to day running - it generates a small amount of - information about operations carried out. - - Levels above 1 will generate considerable amounts - of log data, and should only be used when investigating - a problem. Levels above 3 are designed for use only by developers - and generate HUGE amounts of log data, most of which is extremely - cryptic. - - Note that specifying this parameter here will override - the log level - parameter in the smb.conf - 5 file. - - - - -l <log directory> - The -l parameter specifies a directory - into which the "log.nmbd" log file will be created - for operational data from the running nmbd - server. The default log directory is compiled into Samba - as part of the build process. Common defaults are - /usr/local/samba/var/log.nmb, - /usr/samba/var/log.nmb or - /var/log/log.nmb. Beware: - If the directory specified does not exist, nmbd - will log to the default debug log location defined at compile time. - - - - - - -n <primary NetBIOS name> - This option allows you to override - the NetBIOS name that Samba uses for itself. This is identical - to setting the NetBIOS - name parameter in the smb.conf - 5 file. However, a command - line setting will take precedence over settings in - smb.conf - 5. - - - -p <UDP port number> UDP port number is a positive integer value. @@ -234,18 +160,6 @@ won't need help! - - -s <configuration file> - The default configuration file name - is set at build time, typically as - /usr/local/samba/lib/smb.conf, but - this may be changed when Samba is autoconfigured. - - The file specified contains the configuration details - required by the server. See smb.conf - 5 for more information. - - diff --git a/docs/docbook/manpages/nmblookup.1.sgml b/docs/docbook/manpages/nmblookup.1.sgml index 7dd7f105d7..176050b9c8 100644 --- a/docs/docbook/manpages/nmblookup.1.sgml +++ b/docs/docbook/manpages/nmblookup.1.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -101,12 +103,8 @@ - - -h - Print a help (usage) message. - - - + &popt.common.connection; + &stdarg.help; -B <broadcast address> @@ -131,48 +129,8 @@ - - -d <debuglevel> - debuglevel is an integer from 0 to 10. + &popt.common.samba; - The default value if this parameter is not specified - is zero. - - The higher this value, the more detail will be logged - about the activities of nmblookup. At level - 0, only critical errors and serious warnings will be logged. - - Levels above 1 will generate considerable amounts of - log data, and should only be used when investigating a problem. - Levels above 3 are designed for use only by developers and - generate HUGE amounts of data, most of which is extremely cryptic. - - Note that specifying this parameter here will override - the - log level parameter in the - smb.conf(5) file. - - - - -s <smb.conf> - This parameter specifies the pathname to - the Samba configuration file, - smb.conf(5). This file controls all aspects of - the Samba setup on the machine. - - - - -i <scope> - This specifies a NetBIOS scope that - nmblookup will use to communicate with when - generating NetBIOS names. For details on the use of NetBIOS - scopes, see rfc1001.txt and rfc1002.txt. NetBIOS scopes are - very rarely used, only set this parameter - if you are the system administrator in charge of all the - NetBIOS systems you communicate with. - - - -T This causes any IP addresses found in the diff --git a/docs/docbook/manpages/pdbedit.8.sgml b/docs/docbook/manpages/pdbedit.8.sgml index 113f23f9c4..fc9a212c19 100644 --- a/docs/docbook/manpages/pdbedit.8.sgml +++ b/docs/docbook/manpages/pdbedit.8.sgml @@ -327,9 +327,8 @@ account policy value for bad lockout attempt is now 3 - &stdarg.debuglevel; &stdarg.help; - &stdarg.configfile; + &popt.common.samba; diff --git a/docs/docbook/manpages/profiles.1.sgml b/docs/docbook/manpages/profiles.1.sgml index 0d18c42c82..6ec8055c28 100644 --- a/docs/docbook/manpages/profiles.1.sgml +++ b/docs/docbook/manpages/profiles.1.sgml @@ -54,6 +54,7 @@ + &stdarg.help; diff --git a/docs/docbook/manpages/rpcclient.1.sgml b/docs/docbook/manpages/rpcclient.1.sgml index 933938d438..225bb064ff 100644 --- a/docs/docbook/manpages/rpcclient.1.sgml +++ b/docs/docbook/manpages/rpcclient.1.sgml @@ -61,33 +61,12 @@ - - -A|--authfile=filename - This option allows - you to specify a file from which to read the username and - password used in the connection. The format of the file is - - - -username = <value> -password = <value> -domain = <value> - - - Make certain that the permissions on the file restrict - access from unwanted users. - - - - -c|--command='command string' execute semicolon separated commands (listed below)) - &stdarg.help; - &stdarg.debuglevel; -I IP-address @@ -107,68 +86,10 @@ domain = <value> above. - - - -l|--logfile=logbasename - File name for log/debug files. The extension - '.client' will be appended. The log file is - never removed by the client. - - - - - - - -N|--nopass - instruct rpcclient not to ask - for a password. By default, rpcclient will - prompt for a password. See also the -U - option. - - - - - -s|--conf=smb.conf - Specifies the location of the all-important - smb.conf file. - - - - - - -U|--user=username[%password] - Sets the SMB username or username and password. - - If %password is not specified, the user will be prompted. The - client will first check the USER environment variable, then the - LOGNAME variable and if either exists, the - string is uppercased. If these environmental variables are not - found, the username GUEST is used. - - A third option is to use a credentials file which - contains the plaintext of the username and password. This - option is mainly provided for scripts where the admin does not - wish to pass the credentials on the command line or via environment - variables. If this method is used, make certain that the permissions - on the file restrict access from unwanted users. See the - -A for more details. - - Be cautious about including passwords in scripts. Also, on - many systems the command line of a running process may be seen - via the ps command. To be safe always allow - rpcclient to prompt for a password and type - it in directly. - - - - -W|--workgroup=domain - Set the SMB domain of the username. This - overrides the default domain which is the domain defined in - smb.conf. If the domain specified is the same as the server's NetBIOS name, - it causes the client to log on using the server's local SAM (as - opposed to the Domain SAM). - - + &popt.common.samba; + &popt.common.credentials; + &popt.common.connection; + &stdarg.help; diff --git a/docs/docbook/manpages/smbcacls.1.sgml b/docs/docbook/manpages/smbcacls.1.sgml index 4482019669..03fcbd6fd8 100644 --- a/docs/docbook/manpages/smbcacls.1.sgml +++ b/docs/docbook/manpages/smbcacls.1.sgml @@ -141,11 +141,8 @@ - - -h - Print usage information on the smbcacls - program. - + &stdarg.help; + &popt.common.samba.small; diff --git a/docs/docbook/manpages/smbclient.1.sgml b/docs/docbook/manpages/smbclient.1.sgml index a08f6999e4..cd513398b9 100644 --- a/docs/docbook/manpages/smbclient.1.sgml +++ b/docs/docbook/manpages/smbclient.1.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -115,23 +117,6 @@ - - -s smb.conf - Specifies the location of the all - important smb.conf - 5 file. - - - - -O socket options - TCP socket options to set on the client - socket. See the socket options parameter in - the smb.conf - 5 manual page for the list of valid - options. - - - -R <name resolve order> This option is used by the programs in the Samba @@ -224,70 +209,6 @@ messages. - - -i scope - This specifies a NetBIOS scope that smbclient will - use to communicate with when generating NetBIOS names. For details - on the use of NetBIOS scopes, see rfc1001.txt - and rfc1002.txt. - NetBIOS scopes are very rarely used, only set - this parameter if you are the system administrator in charge of all - the NetBIOS systems you communicate with. - - - - - -N - If specified, this parameter suppresses the normal - password prompt from the client to the user. This is useful when - accessing a service that does not require a password. - - Unless a password is specified on the command line or - this parameter is specified, the client will request a - password. - - - - - - -n NetBIOS name - By default, the client will use the local - machine's hostname (in uppercase) as its NetBIOS name. This parameter - allows you to override the host name and use whatever NetBIOS - name you wish. - - - - - -d debuglevel - debuglevel is an integer from 0 to 10, or - the letter 'A'. - - The default value if this parameter is not specified - is zero. - - The higher this value, the more detail will be logged to - the log files about the activities of the - client. At level 0, only critical errors and serious warnings will - be logged. Level 1 is a reasonable level for day to day running - - it generates a small amount of information about operations - carried out. - - Levels above 1 will generate considerable amounts of log - data, and should only be used when investigating a problem. - Levels above 3 are designed for use only by developers and - generate HUGE amounts of log data, most of which is extremely - cryptic. If debuglevel is set to the letter 'A', then all - debug messages will be printed. This setting - is for developers only (and people who really want - to know how the code works internally). - - Note that specifying this parameter here will override - the log level parameter in the smb.conf (5) - file. - - - -p port This number is the TCP port number that will be used @@ -314,13 +235,7 @@ - - - -h - Print the usage message for the client. - - - + &stdarg.help; -I IP-address @@ -353,59 +268,6 @@ - - -U username[%pass] - Sets the SMB username or username and password. - If %pass is not specified, The user will be prompted. The client - will first check the USER environment variable, then the - LOGNAME variable and if either exists, the - string is uppercased. Anything in these variables following a '%' - sign will be treated as the password. If these environment - variables are not found, the username GUEST - is used. - - If the password is not included in these environment - variables (using the %pass syntax), smbclient will look for - a PASSWD environment variable from which - to read the password. - - A third option is to use a credentials file which - contains the plaintext of the domain name, username and password. This - option is mainly provided for scripts where the admin doesn't - wish to pass the credentials on the command line or via environment - variables. If this method is used, make certain that the permissions - on the file restrict access from unwanted users. See the - -A for more details. - - Be cautious about including passwords in scripts or in - the PASSWD environment variable. Also, on - many systems the command line of a running process may be seen - via the ps command to be safe always allow - smbclient to prompt for a password and type - it in directly. - - - - - -A filenameThis option allows - you to specify a file from which to read the username, domain name, and - password used in the connection. The format of the file is - - - -username = <value> -password = <value> -domain = <value> - - - - If the domain parameter is missing the current workgroup name - is used instead. Make certain that the permissions on the file restrict - access from unwanted users. - - - - -L This option allows you to look at what services @@ -443,16 +305,9 @@ domain = <value> - - - - -W WORKGROUP - Override the default workgroup (domain) specified - in the workgroup parameter of the smb.conf - 5 file for this connection. This may be - needed to connect to some servers. - - + &popt.common.samba; + &popt.common.credentials; + &popt.common.connection; -T tar options @@ -588,14 +443,6 @@ domain = <value> This is particularly useful in scripts and for printing stdin to the server, e.g. -c 'print -'. - - - -k - - Try to authenticate with kerberos. Only useful in - an Active Directory environment. - - diff --git a/docs/docbook/manpages/smbd.8.sgml b/docs/docbook/manpages/smbd.8.sgml index 32837ba903..b31d919a12 100644 --- a/docs/docbook/manpages/smbd.8.sgml +++ b/docs/docbook/manpages/smbd.8.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -122,17 +124,8 @@ - - -h - Prints the help information (usage) - for smbd. - - - - -V - Prints the version number for - smbd. - + &popt.common.samba; + &stdarg.help; -b @@ -140,32 +133,6 @@ Samba was built. - - -d <debug level> - debuglevel is an integer - from 0 to 10. The default value if this parameter is - not specified is zero. - - The higher this value, the more detail will be - logged to the log files about the activities of the - server. At level 0, only critical errors and serious - warnings will be logged. Level 1 is a reasonable level for - day to day running - it generates a small amount of - information about operations carried out. - - Levels above 1 will generate considerable - amounts of log data, and should only be used when - investigating a problem. Levels above 3 are designed for - use only by developers and generate HUGE amounts of log - data, most of which is extremely cryptic. - - Note that specifying this parameter here will - override the log - level parameter in the smb.conf - 5 file. - - - -l <log directory> If specified, @@ -186,14 +153,6 @@ compile time. - - -O <socket options> - See the socket options - parameter in the smb.conf - 5 file for details. - - -p <port number> port number is a positive integer @@ -218,19 +177,6 @@ This parameter is not normally specified except in the above situation. - - - -s <configuration file> - The file specified contains the - configuration details required by the server. The - information in this file includes server-specific - information such as what printcap file to use, as well - as descriptions of all the services that the server is - to provide. See smb.conf - 5 for more information. - The default configuration file name is determined at - compile time. - diff --git a/docs/docbook/manpages/smbstatus.1.sgml b/docs/docbook/manpages/smbstatus.1.sgml index 67d39f2586..98f7e864f6 100644 --- a/docs/docbook/manpages/smbstatus.1.sgml +++ b/docs/docbook/manpages/smbstatus.1.sgml @@ -1,4 +1,7 @@ - + %globalentities; +]> + @@ -54,13 +57,7 @@ gives brief output. - - - -d|--debug=<debuglevel> - sets debugging to specified level - - - + &popt.common.samba; -v|--verbose @@ -96,18 +93,7 @@ - - - - -s|--conf=<configuration file> - The default configuration file name is - determined at compile time. The file specified contains the - configuration details required by the server. See - smb.conf5 - for more information. - - - + &stdarg.help; -u|--user=<username> diff --git a/docs/docbook/manpages/smbtree.1.sgml b/docs/docbook/manpages/smbtree.1.sgml index ce664908bc..3677695d5a 100644 --- a/docs/docbook/manpages/smbtree.1.sgml +++ b/docs/docbook/manpages/smbtree.1.sgml @@ -65,6 +65,8 @@ + &popt.common.samba; + &popt.common.credentials; &stdarg.help; diff --git a/docs/docbook/manpages/swat.8.sgml b/docs/docbook/manpages/swat.8.sgml index a13ba9ff6c..72b3cd65c8 100644 --- a/docs/docbook/manpages/swat.8.sgml +++ b/docs/docbook/manpages/swat.8.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -67,10 +69,9 @@ server. - - -V - Print version number of samba suite - + &popt.common.samba; + &stdarg.help; + diff --git a/docs/docbook/manpages/testparm.1.sgml b/docs/docbook/manpages/testparm.1.sgml index ec8092a926..31a9549416 100644 --- a/docs/docbook/manpages/testparm.1.sgml +++ b/docs/docbook/manpages/testparm.1.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -65,13 +67,9 @@ will prompt for a carriage return after printing the service names and before dumping the service definitions. - - - - -h - Print usage message - - + + &stdarg.help; + &stdarg.version; -L servername diff --git a/docs/docbook/manpages/vfstest.1.sgml b/docs/docbook/manpages/vfstest.1.sgml index c89035d814..8be9271679 100644 --- a/docs/docbook/manpages/vfstest.1.sgml +++ b/docs/docbook/manpages/vfstest.1.sgml @@ -50,7 +50,6 @@ - &stdarg.debuglevel; &stdarg.help; @@ -61,6 +60,8 @@ + &popt.common.samba; + diff --git a/docs/docbook/manpages/wbinfo.1.sgml b/docs/docbook/manpages/wbinfo.1.sgml index 3c7ae11e2c..2e9a811bcb 100644 --- a/docs/docbook/manpages/wbinfo.1.sgml +++ b/docs/docbook/manpages/wbinfo.1.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -226,6 +228,8 @@ + &stdarg.version; + &stdarg.help; diff --git a/docs/docbook/manpages/winbindd.8.sgml b/docs/docbook/manpages/winbindd.8.sgml index a44e195d8c..cae8eb4105 100644 --- a/docs/docbook/manpages/winbindd.8.sgml +++ b/docs/docbook/manpages/winbindd.8.sgml @@ -1,4 +1,6 @@ - + %globalentities; +]> @@ -128,13 +130,9 @@ group: files winbind than a file. - - -d debuglevel - Sets the debuglevel to an integer between - 0 and 100. 0 is for no debugging and 100 is for reams and - reams. To submit a bug report to the Samba Team, use debug - level 100 (see BUGS.txt). - + &popt.common.samba; + &popt.common.connection; + &stdarg.help; -i @@ -168,12 +166,6 @@ group: files winbind - - -s|--conf=smb.conf - Specifies the location of the all-important - smb.conf - 5 file. - -- cgit From 9e809e8dec0356e9f2a5d9c337eb87f124335305 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Mon, 24 Mar 2003 14:32:55 +0000 Subject: Remove documentation for removed options (This used to be commit 2cb23016385a286006a08170188b4e7ca62429d9) --- docs/docbook/manpages/nmbd.8.sgml | 1 - docs/docbook/manpages/winbindd.8.sgml | 1 - 2 files changed, 2 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/nmbd.8.sgml b/docs/docbook/manpages/nmbd.8.sgml index 5f359ff099..f2b4ac5a05 100644 --- a/docs/docbook/manpages/nmbd.8.sgml +++ b/docs/docbook/manpages/nmbd.8.sgml @@ -149,7 +149,6 @@ &popt.common.samba; - &popt.common.connection; -p <UDP port number> diff --git a/docs/docbook/manpages/winbindd.8.sgml b/docs/docbook/manpages/winbindd.8.sgml index cae8eb4105..9923c64ee9 100644 --- a/docs/docbook/manpages/winbindd.8.sgml +++ b/docs/docbook/manpages/winbindd.8.sgml @@ -131,7 +131,6 @@ group: files winbind &popt.common.samba; - &popt.common.connection; &stdarg.help; -- cgit From 068b1e91419bf95373597ef6cf94e76d1ff5af58 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Mon, 24 Mar 2003 18:47:18 +0000 Subject: Add notes for packagers (This used to be commit 9bec6889047814dc00eea102d6c3368d3942db94) --- docs/docbook/devdoc/dev-doc.sgml | 2 ++ docs/docbook/devdoc/packagers.sgml | 40 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 docs/docbook/devdoc/packagers.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml index f10fe72414..5e1af3d3a0 100644 --- a/docs/docbook/devdoc/dev-doc.sgml +++ b/docs/docbook/devdoc/dev-doc.sgml @@ -14,6 +14,7 @@ + ]> @@ -70,5 +71,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt diff --git a/docs/docbook/devdoc/packagers.sgml b/docs/docbook/devdoc/packagers.sgml new file mode 100644 index 0000000000..5042070d68 --- /dev/null +++ b/docs/docbook/devdoc/packagers.sgml @@ -0,0 +1,40 @@ + + + + JelmerVernooij + + + +Notes to packagers + + +Versioning + +Please, please update the version number in +source/include/version.h to include the versioning of your package. This makes it easier to distinguish standard samba builds +from custom-build samba builds (distributions often patch packages). For +example, a good version would be: + + + + + + + + +Modules + +Samba now has support for building parts of samba as plugins. This +makes it possible to, for example, put ldap or mysql support in a seperate +package, thus making it possible to have a normal samba package not +depending on ldap or mysql. To build as much parts of samba +as a plugin, run: + + +./configure --with-shared-modules=rpc,vfs,auth,pdb,charset + + + + + + -- cgit From 148d95ab87b495bff14fdfb2d7cdcbc354171b6e Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Tue, 25 Mar 2003 09:46:57 +0000 Subject: Fix missing tag pairs (This used to be commit 44d9062f91d13b43b1e78c30931a017031f17116) --- docs/docbook/faq/errors.sgml | 4 ++-- docs/docbook/faq/printing.sgml | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/faq/errors.sgml b/docs/docbook/faq/errors.sgml index 905e7c92c2..97619ce704 100644 --- a/docs/docbook/faq/errors.sgml +++ b/docs/docbook/faq/errors.sgml @@ -49,7 +49,7 @@ the samba HOWTO Collection Windows NT in the chapter "Portability" of the samba HOWTO collection - + @@ -62,7 +62,7 @@ the program always prompts for the password if the server is a Samba server. It also ignores the "-N" argument when querying some (but not all) of our NT servers. - + No, it does not ignore -N, it is just that your server rejected the null password in the connection, so smbclient prompts for a password diff --git a/docs/docbook/faq/printing.sgml b/docs/docbook/faq/printing.sgml index cc01a5d3b0..4a58c385bb 100644 --- a/docs/docbook/faq/printing.sgml +++ b/docs/docbook/faq/printing.sgml @@ -20,6 +20,7 @@ setdriver expects the following setup: Use adddriver (with appropriate parameters) to create the driver. note, this will not just update samba's notion of drivers, it will also move the files from the w32x86 and win40 directories to an appropriate subdirectory (based on driver version, I think, but not important enough for me to find out) Use setdriver to associate the driver with a printer + The setdriver call will fail if the printer doesn't already exist in -- cgit From 403ee6701b145574ccfd39e67185a3d247ebaa70 Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Tue, 25 Mar 2003 13:37:36 +0000 Subject: Fixed opened-but-not-closed listitem/varlistentry for LDAPADMINDN (This used to be commit ec6b9e62fbfe417865e8e3b2ba7cc7473709c20e) --- docs/docbook/manpages/smb.conf.5.sgml | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smb.conf.5.sgml b/docs/docbook/manpages/smb.conf.5.sgml index 0f5e751a64..24612d787c 100644 --- a/docs/docbook/manpages/smb.conf.5.sgml +++ b/docs/docbook/manpages/smb.conf.5.sgml @@ -3436,6 +3436,8 @@ df $1 | tail -1 | awk '{print $2" "$4}' 8 man page for more information on how to accmplish this. + + ldap del only sam attr (G) -- cgit From 9985625f5c98a26e993e370c9cf43822350dd1e1 Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Tue, 25 Mar 2003 17:42:46 +0000 Subject: Fix another opened-but-not-closed tag (This used to be commit 1c53686f3a2b2ff220836b76755a184fac0b238e) --- docs/docbook/manpages/smb.conf.5.sgml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smb.conf.5.sgml b/docs/docbook/manpages/smb.conf.5.sgml index 24612d787c..3998932365 100644 --- a/docs/docbook/manpages/smb.conf.5.sgml +++ b/docs/docbook/manpages/smb.conf.5.sgml @@ -3434,8 +3434,7 @@ df $1 | tail -1 | awk '{print $2" "$4}' stored in the private/secrets.tdb file. See the smbpasswd 8 man page for more information on how - to accmplish this. - + to accmplish this. @@ -3455,7 +3454,6 @@ df $1 | tail -1 | awk '{print $2" "$4}' ldap del only sam attr (G) Inverted synonym for ldap delete dn. - -- cgit From 0a37d5fa41364021e5cd754c8f8cd2f4a8f364e5 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Tue, 25 Mar 2003 20:14:41 +0000 Subject: Add info about dual daemon mode (This used to be commit 2018b331a17a4ac485ac03e175ab24d9457a5b77) --- docs/docbook/projdoc/winbind.sgml | 50 +++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 10 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/projdoc/winbind.sgml b/docs/docbook/projdoc/winbind.sgml index 06579617f5..2d38ea44d4 100644 --- a/docs/docbook/projdoc/winbind.sgml +++ b/docs/docbook/projdoc/winbind.sgml @@ -351,15 +351,6 @@ to control access and authenticate users on your Linux box using the winbind services which come with SAMBA 2.2.2. - -There is also some Solaris specific information in -docs/textdocs/Solaris-Winbind-HOWTO.txt. -Future revisions of this document will incorporate that -information. - - - - Introduction @@ -627,6 +618,19 @@ command as root: root# /usr/local/samba/bin/winbindd + +Winbindd can now also run in 'dual daemon mode'. This will make it +run as 2 processes. The first will answer all requests from the cache, +thus making responses to clients faster. The other will +update the cache for the query that the first has just responded. +Advantage of this is that responses stay accurate and are faster. +You can enable dual daemon mode by adding '-B' to the commandline: + + + +root# /usr/local/samba/bin/winbindd -B + + I'm always paranoid and like to make sure the daemon is really running... @@ -756,9 +760,22 @@ start() { } +If you would like to run winbindd in dual daemon mode, replace +the line + + daemon /usr/local/samba/bin/winbindd + + +in the example above with: + + + daemon /usr/local/samba/bin/winbindd -B +. + + The 'stop' function has a corresponding entry to shut down the -services and look s like this: +services and looks like this: @@ -842,6 +859,19 @@ echo Starting Winbind Daemon ;; esac + +Again, if you would like to run samba in dual daemon mode, replace + + /usr/local/samba/bin/winbindd + + +in the script above with: + + + /usr/local/samba/bin/winbindd -B + + + -- cgit From bb7a2a1334a1a96a250c0a9282c9a11458766d16 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Tue, 25 Mar 2003 20:49:13 +0000 Subject: Add documentation on unicode (This used to be commit cdfb0161adb37f70247b047eb93b92cfcf11783b) --- docs/docbook/projdoc/samba-doc.sgml | 2 + docs/docbook/projdoc/unicode.sgml | 93 +++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/docbook/projdoc/unicode.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml index efb14d4b6c..c1662ee3bf 100644 --- a/docs/docbook/projdoc/samba-doc.sgml +++ b/docs/docbook/projdoc/samba-doc.sgml @@ -24,6 +24,7 @@ + ]> @@ -116,6 +117,7 @@ part each cover one specific feature. &SPEED; &GroupProfiles; &SecuringSamba; +&unicode; diff --git a/docs/docbook/projdoc/unicode.sgml b/docs/docbook/projdoc/unicode.sgml new file mode 100644 index 0000000000..a467a0d4e7 --- /dev/null +++ b/docs/docbook/projdoc/unicode.sgml @@ -0,0 +1,93 @@ + + + + JelmerVernooij + + Samba Team +
jelmer@samba.org
+ + + 25 March 2003 + + +Unicode/Charsets + + +What are charsets and unicode? + + +Computers communicate in numbers. In texts, each number will be +translated to a corresponding letter. The meaning that will be assigned +to a certain number depends on the character set(charset) + that is used. +A charset can be seen as a table that is used to translate numbers to +letters. Not all computers use the same charset (there are charsets +with German umlauts, Japanese characters, etc). Usually a charset contains +256 characters, which means that storing a character with it takes +exactly one byte. + + +There are also charsets that support even more characters, +but those need twice(or even more) as much storage space. These +charsets can contain 256 * 256 = 65536 characters, which +is more then all possible characters one could think of. They are called +multibyte charsets (because they use more then one byte to +store one character). + + + +A standardised multibyte charset is unicode, info available at +www.unicode.org. +Big advantage of using a multibyte charset is that you only need one; no +need to make sure two computers use the same charset when they are +communicating. + + +Old windows clients used to use single-byte charsets, named +'codepages' by microsoft. However, there is no support for +negotiating the charset to be used in the smb protocol. Thus, you +have to make sure you are using the same charset when talking to an old client. +Newer clients (Windows NT, 2K, XP) talk unicode over the wire. + + + + +Samba and charsets + + +As of samba 3.0, samba can (and will) talk unicode over the wire. Internally, +samba knows of three kinds of character sets: + + + + + unix charset + + This is the charset used internally by your operating system. + The default is ASCII, which is fine for most + systems. + + + + + display charset + This is the charset samba will use to print messages + on your screen. It should generally be the same as the unix charset. + + + + + dos charset + This is the charset samba uses when communicating with + DOS and Windows 9x clients. It will talk unicode to all newer clients. + The default depends on the charsets you have installed on your system. + Run testparm -v | grep "dos charset" to see + what the default is on your system. + + + + + + + + -- cgit From adb1aa87f0cdd2a832cecda205e5f076b06fece7 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Tue, 25 Mar 2003 22:15:57 +0000 Subject: Add example version identifier (This used to be commit 0558cae208067aa1e10060f22f12b2b8c09c53b1) --- docs/docbook/devdoc/packagers.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/packagers.sgml b/docs/docbook/devdoc/packagers.sgml index 5042070d68..fb47c7305c 100644 --- a/docs/docbook/devdoc/packagers.sgml +++ b/docs/docbook/devdoc/packagers.sgml @@ -16,7 +16,7 @@ from custom-build samba builds (distributions often patch packages). For example, a good version would be: - +Version 2.999+3.0.alpha21-5 for Debian -- cgit From 03414dcb267d27b157b14b76f43eeffd03f57762 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Tue, 25 Mar 2003 22:51:38 +0000 Subject: Add notes about the rebuilding of files (This used to be commit 0ab6e96c9b32526936878da62b3cc00edd0ac27c) --- docs/docbook/devdoc/modules.sgml | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/devdoc/modules.sgml b/docs/docbook/devdoc/modules.sgml index 99cba605bd..0bcdadc66c 100644 --- a/docs/docbook/devdoc/modules.sgml +++ b/docs/docbook/devdoc/modules.sgml @@ -63,11 +63,8 @@ it is here currently (from include/config.h): -These functions should be called before the subsystem is used. That can be -done either from the executable that will be using the subsystem ( -static_init_rpc is called from the main() function of smbd), or -from the subsystem itself when it's first used (like passdb's -lazy_initialise_passdb does). +These functions should be called before the subsystem is used. That +should be done when the subsystem is initialised or first used. @@ -138,10 +135,22 @@ for each module and SMB_SUBSYSTEM() for each subsystem. Syntax: -SMB_MODULE($MODULE_subsystem_backend, subsystem_backend, object files, plugin name, subsystem name) +SMB_MODULE(subsystem_backend, object files, plugin name, subsystem name, static_action, shared_action) SMB_SUBSYSTEM(subsystem) +Also, make sure to add the correct directives to +Makefile.in. @SUBSYSTEM_STATIC@ +will be replaced with a list of objects files of the modules that need to +be linked in statically. @SUBSYSTEM_MODULES@ will +be replaced with the names of the plugins to build. + + +You must make sure all .c files that contain defines that can +be changed by ./configure are rebuilded in the 'modules_clean' make target. +Practically, this means all c files that contain static_init_subsystem; calls need to be rebuilded. + + -- cgit From 6f75da500b75c17c8b71b6b682f5025144061891 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Tue, 25 Mar 2003 23:03:03 +0000 Subject: Fix two typos (This used to be commit c682d5abf310e445f1629e9b48a15d10b176ed39) --- docs/docbook/manpages/smb.conf.5.sgml | 2 +- docs/docbook/manpages/winbindd.8.sgml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/manpages/smb.conf.5.sgml b/docs/docbook/manpages/smb.conf.5.sgml index 3998932365..0968faa584 100644 --- a/docs/docbook/manpages/smb.conf.5.sgml +++ b/docs/docbook/manpages/smb.conf.5.sgml @@ -2374,7 +2374,7 @@ df $1 | tail -1 | awk '{print $2" "$4}' charset Samba should talk to DOS clients. - The default depends on which charsets you have instaled. + The default depends on which charsets you have installed. Samba tries to use charset 850 but falls back to ASCII in case it is not available. Run testparm 1 to check the default on your system. diff --git a/docs/docbook/manpages/winbindd.8.sgml b/docs/docbook/manpages/winbindd.8.sgml index 9923c64ee9..177265caf1 100644 --- a/docs/docbook/manpages/winbindd.8.sgml +++ b/docs/docbook/manpages/winbindd.8.sgml @@ -161,7 +161,7 @@ group: files winbind as 2 threads. The first will answer all requests from the cache, thus making responses to clients faster. The other will update the cache for the query that the first has just responded. - Advantage of this is that responses are accurate and fast. + Advantage of this is that responses stay accurate and are faster. -- cgit From 4474f67fa3f915f7e09fddc3df42cd97403752f9 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 26 Mar 2003 11:09:12 +0000 Subject: - Patch from John to update PDC-HOWTO, add ServerType and CUPS (not finished yet) - Regenerate docs - Update docs-status (This used to be commit adbb714ade8ab6f4e9b5d80f0f85041746c0edf1) --- docs/docbook/projdoc/CUPS-printing.sgml | 1184 +++++++++++++++++++++++++++++ docs/docbook/projdoc/Samba-PDC-HOWTO.sgml | 162 ++-- docs/docbook/projdoc/ServerType.sgml | 140 ++++ docs/docbook/projdoc/passdb.sgml | 77 +- docs/docbook/projdoc/samba-doc.sgml | 2 + docs/docbook/projdoc/security_level.sgml | 2 +- docs/docbook/projdoc/unicode.sgml | 10 +- 7 files changed, 1495 insertions(+), 82 deletions(-) create mode 100644 docs/docbook/projdoc/CUPS-printing.sgml create mode 100644 docs/docbook/projdoc/ServerType.sgml (limited to 'docs/docbook') diff --git a/docs/docbook/projdoc/CUPS-printing.sgml b/docs/docbook/projdoc/CUPS-printing.sgml new file mode 100644 index 0000000000..bfd23e3c6c --- /dev/null +++ b/docs/docbook/projdoc/CUPS-printing.sgml @@ -0,0 +1,1184 @@ + + + + + + John HTerpstra + + Samba Team +
+ jht@samba.org +
+ + + + KurtPfeifle + +
kpfeifle@danka.de
+ + + (25 March 2003) + + +CUPS Printing Support + + +Introduction + + +The Common Unix Print System (CUPS) has become very popular, but to many it is +a very mystical tool. There is a great deal of uncertainty regarding CUPS and how +it works. The result is seen in a large number of posting on the samba mailing lists +expressing frustration when MS Windows printers appear not to work with a CUPS +backr-end. +/para> + + +This is a good time to point out how CUPS can be used and what it does. CUPS is more +than just a print spooling system - it is a complete printer management system that +complies with HTTP and IPP protocols. It can be managed remotely via a web browser +and it can print using http and ipp protocols. + + + +CUPS allows to creation of RAW printers (ie: NO file format translation) as well as +SMART printers (ie: CUPS does file format conversion as required for the printer). In +many ways this gives CUPS similar capabilities to the MS Windows print monitoring +system. Of course, if you are a CUPS advocate, you would agrue that CUPS is better! +In any case, let us now move on to explore how one may configure CUPS for interfacing +with MS Windows print clients via Samba. + + + + + +CUPS - RAW Print Through Mode + + +When CUPS printers are configured for RAW print-through mode operation it is the +responsibility of the Samba client to fully render the print job (file) in a format +that is suitable for direct delivery to the printer. In this case CUPS will NOT +do any print file format conversion work. + + + +The CUPS files that need to be correctly set for RAW mode printers to work are: + + + /etc/cups/mime.types/etc/cups/mime.convs + + +Both contain entries that must be uncommented to allow RAW mode +operation. + + + +Firstly, to enable CUPS based printing from Samba the following options must be +enabled in your smb.conf file [globals] section: + + + printing = CUPS + + printcap = CUPS + + +When these parameters are specified the print directives in smb.conf (as well as in +samba itself) will be ignored because samba will directly interface with CUPS through +it's application program interface (API) - so long as Samba has been compiled with +CUPS library (libcups) support. If samba has NOT been compiled with CUPS support then +printing will use the System V AT&T command set with the -oraw +option automatically passing through. + + + +Cupsomatic (an enhanced printing utility that is part of some CUPS implementations) +on the Samba/CUPS server does *not* add any features if a file is really +printed "raw". However, if you have loaded the driver for the Windows client from +the CUPS server, using the "cupsaddsmb" utility, and if this driver is one using +a "Foomatic" PPD, the PJL header in question is already added on the Windows client, +at the time when the driver initially generated the PostScript data and CUPS in true +"-oraw" manner doesn't remove this PJL header and passes the file "as is" to its +printer communication backend. + + + +NOTE: editing in the "mime.convs" and the "mime.types" file does not *enforce* +"raw" printing, it only *allows* it. + + + +Print files that arrive from MS Windows printing are "auto-typed" by CUPS. This aids +the process of determining proper treatment while in the print queue system. + + + + Files generated by PCL drivers and directed at PCK printers get auto-typed as + application/octet-stream. Unknown file format types also + get auto-typed with this tag. + + + + Files generated by a Postscript driver and directed at a Postscript printer + are auto-typed depending on the auto-detected most suitable MIME type as: + + + * application/postscript + * application/vnd.cups-postscript + + + + + + + +"application/postscript" first goes thru the "pstops" filter (where the page counting +and accounting takes place). The outcome will be of MIME type +"application/vnd.cups-postscript". The pstopsfilter reads and uses information from +the PPD and inserts user-provided options into the PostScript file. As a consequence, +the filtered file could possibly have an unwanted PJL header. + + + +"application/postscript" will be all files with a ".ps", ".ai", ".eps" suffix or which +have as their first character string one of "%!" or "<04>%". + + + +"application/vnd.cups-postscript" will files which contain the string +"LANGUAGE=POSTSCRIPT" (or similar variations with different capitalization) in the +first 512 bytes, and also contain the "PJL super escape code" in the first 128 bytes +("<1B>%-12345X"). Very likely, most PostScript files generated on Windows using a CUPS +or other PPD, will have to be auto-typed as "vnd.cups-postscript". A file produced +with a "Generic PostScript driver" will just be tagged "application/postscript". + + + +Once the file is in "application/vnd.cups-postscript" format, either "pstoraster" +or "cupsomatic" will take over (depending on the printer configuration, as +determined by the PPD in use). + + + +A printer queue with *no* PPD associated to it is a "raw" printer and all files +will go directly there as received by the spooler. The exeptions are file types +"application/octet-stream" which need "passthrough feature" enabled. +"Raw" queues don't do any filtering at all, they hand the file directly to the +CUPS backend. This backend is responsible for the sending of the data to the device +(as in the "device URI" notation as lpd://, socket://, smb://, ipp://, http://, +parallel:/, serial:/, usb:/ etc.) + + + +"cupsomatic"/Foomatic are *not* native CUPS drivers and they don't ship with CUPS. +They are a Third Party add-on, developed at Linuxprinting.org. As such, they are +a brilliant hack to make all models (driven by Ghostscript drivers/filters in +traditional spoolers) also work via CUPS, with the same (good or bad!) quality +as in these other spoolers. "cupsomatic" is only a vehicle to execute a ghostscript +commandline at that stage in the CUPS filtering chain, where "normally" the native +CUPS "pstoraster" filter would kick in. cupsomatic by-passes pstoraster, "kidnaps" +the printfile from CUPS away and re-directs it to go through Ghostscipt. CUPS accepts this, +because the associated CUPS-O-Matic-/Foomatic-PPD specifies: + + + + *cupsFilter: "application/vnd.cups-postscript 0 cupsomatic" + + + +This line persuades CUPS to hand the file to cupsomatic, once it has successfully +converted it to the MIME type "application/vnd.cups-postscript". This conversion will not +happen for Jobs arriving from Windows which are auto-typed "application/octet-stream", +with the according changes in "/etc/cups/mime.types" in place. + + + +CUPS is widely configurable and flexible, even regarding its filtering mechanism. +Another workaround in some situations would be to have +in "/etc/cups/mime.types" entries as follows: + + + + application/postscript application/vnd.cups-raw 0 - + application/vnd.cups-postscript application/vnd.cups-raw 0 - + + + +This would prevent all Postscript files from being filtered (rather, they will go +thru the virtual "nullfilter" denoted with "-"). This could only be useful for +PS printers. If you want to print PS code on non-PS printers an entry as follows +could be useful: + + + + */* application/vnd.cups-raw 0 - + + + +and would effectively send *all* files to the backend without further processing. + + + +Lastly, you could have the following entry: + + + + application/vnd.cups-postscript application/vnd.cups-raw 0 my_PJL_stripping_filter + + + +You will need to write a "my_PJL_stripping_filter" (could be a shellscript) that +parses the PostScript and removes the unwanted PJL. This would need to conform to +CUPS filter design (mainly, receive and pass the parameters printername, job-id, +username, jobtitle, copies, print options and possibly the filename). It would +be installed as world executable into "/usr/lib/cups/filters/" and will be called +by CUPS if it encounters a MIME type "application/vnd.cups-postscript". + + + +CUPS can handle "-o job-hold-until=indefinite". This keeps the job in the queue +"on hold". It will only be printed upon manual release by the printer operator. +This is a requirement in many "central reproduction departments", where a few +operators manage the jobs of hundreds of users on some big machine, where no +user is allowed to have direct access. (The operators often need to load the +proper paper type before running the 10.000 page job requested by marketing +for the mailing, etc.). + + + + + +The CUPS Filter Chains + + +The following diagrams reveal how CUPS handles print jobs. + + + +######################################################################### +# +# CUPS in and of itself has this (general) filter chain (CAPITAL +# letters are FILE-FORMATS or MIME types, other are filters (this is +# true for pre-1.1.15 of pre-4.3 versions of CUPS and ESP PrintPro): +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT +# | +# | +# V +# pstoraster # as shipped with CUPS, independent from any Ghostscipt +# | # installation on the system +# | (= "postscipt interpreter") +# | +# V +# APPLICATION/VND.CUPS-RASTER +# | +# | +# V +# rasterto (f.e. Gimp-Print filters may be plugged in here) +# | (= "raster driver") +# | +# V +# SOMETHING-DEVICE-SPECIFIC +# | +# | +# V +# backend +# +# +# ESP PrintPro has some enhanced "rasterto" filters as compared to +# CUPS, and also a somewhat improved "pstoraster" filter. +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +######################################################################### + + + +######################################################################### +# +# This is how "cupsomatic" comes into play: +# ========================================= +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT ----------------+ +# | | +# | V +# V cupsomatic +# pstoraster (constructs complicated +# | (= "postscipt interpreter") Ghostscript commandline +# | to let the file be +# V processed by a +# APPLICATION/VND.CUPS-RASTER "-sDEVICE=" +# | call...) +# | | +# V | +# rasterto V +# | (= "raster driver") +-------------------------+ +# | | Ghostscript at work.... | +# V | | +# SOMETHING-DEVICE-SPECIFIC *-------------------------+ +# | | +# | | +# V | +# backend <------------------------------------+ +# | +# | +# V +# THE PRINTER +# +# +# Note, that cupsomatic "kidnaps" the printfile after the +# "APPLICATION/VND.CUPS-POSTSCRPT" stage and deviates it through +# the CUPS-external, systemwide Ghostscript installation, bypassing the +# "pstoraster" filter (therefor also bypassing the CUPS-raster-drivers +# "rasterto", and hands the rasterized file directly to the CUPS +# backend... +# +# cupsomatic is not made by the CUPS developers. It is an independent +# contribution to printing development, made by people from +# Linuxprinting.org. (see also http://www.cups.org/cups-help.html) +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +######################################################################### + + + +######################################################################### +# +# And this is how it works for ESP PrintPro from 4.3: +# =================================================== +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT +# | +# | +# V +# gsrip +# | (= "postscipt interpreter") +# | +# V +# APPLICATION/VND.CUPS-RASTER +# | +# | +# V +# rasterto (f.e. Gimp-Print filters may be plugged in here) +# | (= "raster driver") +# | +# V +# SOMETHING-DEVICE-SPECIFIC +# | +# | +# V +# backend +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +######################################################################### + + + +######################################################################### +# +# This is how "cupsomatic" would come into play with ESP PrintPro: +# ================================================================ +# +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT ----------------+ +# | | +# | V +# V cupsomatic +# gsrip (constructs complicated +# | (= "postscipt interpreter") Ghostscript commandline +# | to let the file be +# V processed by a +# APPLICATION/VND.CUPS-RASTER "-sDEVICE=" +# | call...) +# | | +# V | +# rasterto V +# | (= "raster driver") +-------------------------+ +# | | Ghostscript at work.... | +# V | | +# SOMETHING-DEVICE-SPECIFIC *-------------------------+ +# | | +# | | +# V | +# backend <------------------------------------+ +# | +# | +# V +# THE PRINTER +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +######################################################################### + + + +######################################################################### +# +# And this is how it works for CUPS from 1.1.15: +# ============================================== +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT-----+ +# | +# +------------------v------------------------------+ +# | Ghostscript | +# | at work... | +# | (with | +# | "-sDEVICE=cups") | +# | | +# | (= "postscipt interpreter") | +# | | +# +------------------v------------------------------+ +# | +# | +# APPLICATION/VND.CUPS-RASTER <-------+ +# | +# | +# V +# rasterto +# | (= "raster driver") +# | +# V +# SOMETHING-DEVICE-SPECIFIC +# | +# | +# V +# backend +# +# +# NOTE: since version 1.1.15 CUPS "outsourced" the pstoraster process to +# Ghostscript. GNU Ghostscript needs to be patched to handle the +# CUPS requirement; ESP Ghostscript has this builtin. In any case, +# "gs -h" needs to show up a "cups" device. pstoraster is now a +# calling an appropriate "gs -sDEVICE=cups..." commandline to do +# the job. It will output "application/vnd.cup-raster", which will +# be finally processed by a CUPS raster driver "rasterto" +# Note the difference to "cupsomatic", which will *not* output +# CUPS-raster, but a final version of the printfile, ready to be +# sent to the printer. cupsomatic also doesn't use the "cups" +# devicemode in Ghostscript, but one of the classical devicemodes.... +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +######################################################################### + + + +######################################################################### +# +# And this is how it works for CUPS from 1.1.15, with cupsomatic included: +# ======================================================================== +# +# -FILEFORMAT +# | +# | +# V +# tops +# | +# | +# V +# APPLICATION/POSTSCRIPT +# | +# | +# V +# pstops +# | +# | +# V +# APPLICATION/VND.CUPS-POSTSCRIPT-----+ +# | +# +------------------v------------------------------+ +# | Ghostscript . Ghostscript at work.... | +# | at work... . (with "-sDEVICE= | +# | (with . " | +# | "-sDEVICE=cups") . | +# | . | +# | (CUPS standard) . (cupsomatic) | +# | . | +# | (= "postscript interpreter") | +# | . | +# +------------------v--------------v---------------+ +# | | +# | | +# APPLICATION/VND.CUPS-RASTER <-------+ | +# | | +# | | +# V | +# rasterto | +# | (= "raster driver") | +# | | +# V | +# SOMETHING-DEVICE-SPECIFIC <------------------------+ +# | +# | +# V +# backend +# +# +# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to +# CUPS and ESP PrintPro plug-in where rasterto is noted. +# +########################################################################## + + + + + + +CUPS Print Drivers and Devices + + +CUPS ships with good support for HP LaserJet type printers. You can install +the driver as follows: + + + + lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd + + + +(The "-m" switch will retrieve the "laserjet.ppd" from the standard repository +for not-yet-installed-PPDs, which CUPS typically stores in +filename>/usr/share/cups/model. Alternatively, you may use +"-P /absolute/filesystem/path/to/where/there/is/PPD/your.ppd"). + + + + +Windows printing involves some more steps.... + +But let me first point out some more general things about printer "drivers" +for Linux/Unix (yes, and for Mac OS X now!), be it you use CUPS or one of +the venerable (I'd even call them "ancient" and "rusty" now...) printing +systems. + +You -- and everybody else, for that matter -- should always also consult the +database on linuxprinting.org for all recommendations about "which driver +is best used for which printer": + + http://www.linuxprinting.org/printer_list.cgi + +There select your model and click on "Show". You'll arrive at a page listing +all drivers working with your model. There will always be *one* "recommended" +one. Try this one first. In your case ("HP LaserJet 4 Plus"), you'll arrive +here: + + http://www.linuxprinting.org/show_printer.cgi?recnum=75104 + +The recommended driver is "ljet4". It has a link to the page for the ljet4 +driver too: + + http://www.linuxprinting.org/show_driver.cgi?driver=ljet4 + +On the driver's page, you'll find various important and detailed infos about +how to use that driver within various spoolers. You can generate a PPD for +CUPS. The PPD contains all the info about how to use your model and the driver; +this is, once installed, working transparently for the user -- you'll only +need to choose resolution, paper size etc. from the web-based menu or from +the print dialog GUI or from the commandline... + +On the driver's page, choose to use the "PPD-O-Matic" online PPD generator +program. Select your model and click "Generate PPD file". When you safe the +appearing ASCII text file, don't use "cut'n'past" (as it will possible corrupt +line endings and tabs), but use "Save as..." in your browser's menu. Save it +at "/some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd" + +Then install the printer: + + "lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -P /some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd" + +Note, that for all the "Foomatic-PPDs" from Linuxprinting.org, you also need +a special "CUPS filter" named "cupsomatic". Get the latest version of +"cupsomatic" from + + http://www.linuxprinting.org/cupsomatic + +This needs to be copied to "/usr/lib/cups/filter/cupsomatic" and be made world +executable. This filter is needed to read and act upon the specially encoded +Foomatic comments, embedded in the printfile, which in turn are used to +construct (transparently for you, the user) the complicated ghostscript command +line needed for your printer/driver combo. + +You can have a look at all the options for the Ghostscript commandline supported +by your printer and the ljet4 driver by going to the section "Execution details", +selecting your model (Laserjet 4 Plus) and clicking on "Show execution details". +This will bring up this web page: + + http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details + +The ingenious thing is this: the database is kept very current. If there +is a bug fix and an improvement somewhere in the database, you will +always get the most current and stable and feature-rich driver by following +the steps described above... Till Kamppeter from MandrakeSoft is doing an +excellent job here, and too few people still know about it. (So if you use +it often, please send him a note of your appreciation sometime...) + +(The latest and greatest improvement now is support for "custom page sizes" +for all those printers which support it...) + +"cupsomatic" is documented here: + + http://www.linuxprinting.org/cups-doc.html + +More printing tutorial info may be found here: + + http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/ + +Note, that *all* the Foomatic drivers listed on Linuxprinting.org (now +approaching the "all-time high" number of 1.000 for the supported models) +are using a special filtering chain involving Ghostscript, as described +in great detail in the Samba CVS sources (for 2.2.x) in + + docs/textdocs/CUPS-PrintingInfo.txt + +To sum it up: + +* having a "foomatic+" PPD is not enough to print with CUPS + (but it is *one* important component) +* you also need the "cupsomatic" filter script (Perl) in "/usr/lib/cups/filters/" +* you need Perl to make cupsomatic run +* you also need Ghostscript (because it is called and controlled by the + PPD/cupsomatic combo in a way to fit your printermodel/driver combo...) +* your Ghostscript *must*, depending on the driver/model, contain support + for a certain "device" (as shown by "gs -h") + +In the case of the "hpijs" driver, you need a Ghostscript version, which +is showing a "ijs" amongst its supported devices in "gs -h". In the case of +"hpijs+foomatic", a valid ghostscript commandline would be reading like this: + + gs -q -dBATCH -dPARANOIDSAFER -dQUIET -dNOPAUSE -sDEVICE=ijs \ + -sIjsServer=hpijs -dDuplex= \ + -r,PS:MediaPosition= -dIjsUseOutputFD \ + -sOutputFile=- - + +Note, that with CUPS and the "hpijs+foomatic" PPD (plus Perl and cupsomatic) +you don't need to remember this. You can choose the available print options +thru a GUI print command (like "glp" from ESP's commercially supported +PrintPro software, or KDE's "kprinter", or GNOME's "gtklp" or the independent +"xpp") or the CUPS web interface via human-readable drop-down selection +menus..... + +If you use "ESP Ghostscript" (also under the GPL, provided by Easy Software +Products, the makers of CUPS, downloadable from http://www.cups.org/software.html, +co-maintained by the developers of linuxprinting.org), you are guaranteed to +have in use the most uptodate, bug-fixed, enhanced and stable version of a Free +Ghostscript. It contains support for ~300 devices, whereas plain vanilla +GNU Ghostscript 7.05 only has ~200.... + +>>/ However, I can only print a Cups test page, from the web interface. when I +/>>/ try to print a windows test page, it acts like the job was never sent. +/ + * Can you print "standard" jobs from the CUPS machine? + + * Are the jobs from Windows visible in the Web interface on CUPS + (http://localhost:631/)? + +*Most important:* What kind of printer driver are you using on the Windows clients??? + +You can try to get a more detailed debugging info by setting "LogLevel debug" in +"/etc/cups/cupsd.conf", re-start cupsd and investigate "/var/log/cups/error_log" +for the whereabouts of your Windows-originating printjobs: + + * what does the "auto-typing" line say? which is the "MIME type" CUPS thinks + is arriving from the Windows clients? + * are there "filter" available for this MIME type? + * are there "filter rules" defined in "/etc/cups/mime.convs" for this MIME type? + + + + + + + +Limiting the number of pages users can print + + +The feature you want is dependent on the real print subsystem +you're using. Samba's part is always to receive the job files +from the clients (filtered *or* unfiltered) and hand it over +to this printing subsystem. + +Of course one could "hack" things with one's own scripts. + +But there is CUPS (Common Unix Printing System). CUPS supports "quotas". +Quotas can be based on sizes of jobs or on the number of pages or both, +and are spanning any time period you want. + +This is an example command how root would set a print quota in CUPS, +assuming an existing printer named "quotaprinter": + + + + lpadmin -p quotaprinter -o job-quota-period=604800 -o job-k-limit=1024 -o job-page-limit=100 + + + +This would limit every single user to print 100 pages or 1024 KB of +data (whichever comes first) within the last 604.800 seconds ( = 1 week). + +For CUPS to count correctly, the printfile needs to pass the CUPS +"pstops" filter, otherwise it uses a "dummy" count of "1". (Some +printfiles don't pass it -- f.e. image files -- but then those are +mostly 1 page jobs anyway). This also means, proprietary drivers for +the target printer running on the client computers and CUPS/Samba +then spooling these files as "raw" (i.e. leaving them untouched, not +filtering them), will be counted as "1-pagers" too! + +You need to send PostScript from the clients (i.e. run a PostScript +driver there) for having the chance to get accounting done. If the +printer is a non-PostScript model, you need to let CUPS do the job to +convert the file to a print-ready format for the target printer. This +will be working for currently ~1.000 different printer models, see + + + + http://www.linuxprinting.org/printer_list.cgi + + + +Before CUPS-1.1.16 your only option was to use the Adobe PostScript +Driver on the Windows clients. The output of this driver was not always +passed thru the "pstops" filter on the CUPS/Samba side, and therefor was +not counted correctly (the reason is that it often --- depending on the +"PPD" being used --- did write a "PJL"-header in front of the real +PostScript which made CUPS to skip the pstops and go directy to +the "pstoraster" stage). + + From CUPS-1.1.16 onward you can use the "CUPS PostScript Driver +for Windows NT/2K/XP clients" (it is tagged in the download area of +http://www.cups.org/ as the "cups-samba-1.1.16.tar.gz" package). +It is *not* working for Win9x/ME clients. But it.... + + ...it guarantees to not write an PJL-header; + ...it guarantees to still read and support all PJL-options named + in the driver PPD with its own means; + ...it guarantees the file going thru the "pstops" filter on the + CUPS/Samba server; + ...it guarantees to page-count correctly the printfile... + +You can read more about the setup of this combination in the +manpage for "cupsaddsmb" (only present with CUPS installed, only +current with CUPS 1.1.16). + +These are the items CUPS logs in the "page_log" for every single +*page* of a job: + +* Printer name +* User name +* Job ID +* Time of printing +* the page number +* the number of copies +* a billing info string (optional) + +Here is an extract of my CUPS server's page_log file to illustrate +the format and included items: + +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 1 2 #marketing +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 2 2 #marketing +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 3 2 #marketing +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 4 2 #marketing +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 5 2 #marketing +infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 6 2 #marketing + +This was Job ID "40", printed on "infotec_IS2027" by user "kurt", +a 6-page job printed in 2 copies and billed to "#marketing"... + +Which flaws or shortcomings are there? + + * the ones named above; + * CUPS really counts the job pages being *processsed in software* + (going thru the "RIP") rather than the physical sheets successfully + leaving the printing device -- if there is a jam while printing + the 5th sheet out of 1000 and the job is aborted by the printer, + the "page count" will still show the figure of 1000 for that + job; + * all quotas are the same for all users (no flexibility to + give the boss a higher quota than the clerk) + * no support for groups; + * no means to read out the current balance or "used-up" + number of current quota; + * a user having used up 99 sheets of 100 quota will still be + able to send and print a 1.000 sheet job; + * a user being denied a job because of a filled-up quota + doesn't get a meaningful error message from CUPS other than + "client-error-not-possible". + +But this is the best system out there currently. And there are +huge improvements under development: + +--> page counting will go into the "backends" (these talk directly + to the printer and will increase the count in sync with the + actual printing process -- a jam at the 5th sheet will lead + to a stop in the counting...) + +--> quotas will be handled more flexibly; + +--> probably there will be support for users to inquire their + "accounts" in advance; + +--> probably there will be support for some other tools around + this topic... + +Other than the current stage of the CUPS development, I don't +know any other ready-to-use tool which you could consider. + + + +You can download the driver files from http://www.cups.org/software.html. It +is a separate package from the CUPS base software files, tagged as "CUPS 1.1.16 +Windows NT/2k/XP Printer Driver for SAMBA (tar.gz, 192k)". The filename to +download is "cups-samba-1.1.16.tar.gz". Upon untar-/unzip-ping it will reveal +the files + + cups-samba.install + cups-samba.license + cups-samba.readme + cups-samba.remove + cups-samba.ss + +These have been packaged with the ESP meta packager software "EPM". The +*.install and *.remove files are simple shell script, which untars the +*.ss (which is nothing else than a tar-archive) and puts its contents +into "/usr/share/cups/drivers/". Its contents are 3 files: + + cupsdrvr.dll + cupsui.dll + cups.hlp + +[ ATTENTION: due to a bug the current release puts the "cups.hlp" into + "/usr/share/drivers/" instead of "/usr/share/cups/drivers/". To work + around this, copy/move the file after running the "./cups-samba.install" + script manually to the right place: + + "cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/" ] + +This new CUPS PostScript driver is currently binary-only, but free (as in +free beer); no source code is provided (yet). The reason is this: it has +been developed with the help of the Microsoft Driver Developer Kit (DDK) +and compiled with Microsoft Visual Studio 6. It is not clear to the driver +developers if they are allowed to distribute the whole of the source code +as Free Software. However, they will likely release the "diff" in source +code under the GPL, so anybody with a license of Visual Studio and a DDK +will be able to compile for him/herself. + +Once you have run the install script (and possibly manually moved the +"cups.hlp" file to "/usr/share/cups/drivers/"), the driver is ready to be +put into Samba's [print$] share (which often maps to "/etc/samba/drivers/" +and contains a subdir tree with WIN40 and W32X86 branches), by running +"cupsaddsmb" (see also "man cupsaddsmb" for CUPS 1.1.16). [Don't forget to +put root into the smbpasswd file by running "smbpasswd" should you run +this whole procedure for the first time.] Once the driver files are in the +[print$] share, they are ready to be downloaded and installed by the +Win NT/2k/XP clients. + +NOTE 1: Win 9x/ME clients won't work with this driver. For these you'd + still need to use the ADOBE*.* drivers as previously. + +NOTE 2: It is not harming if you've still the ADOBE*.* driver files from + previous installations in the "/usr/share/cups/drivers/" directory. + The new cupsaddsmb (from 1.1.16) will automatically use the + "newest" installed driver (which here then is the CUPS drivers). + +NOTE 3: Should your Win clients have had the old ADOBE*.* files and the + Adobe PostScript drivers installed, the download and installation + of the new CUPS PostScript driver for Windows NT/2k/XP will fail + at first. + It is not enough to "delete" the printer (as the driver files + will still be kept by the clients and re-used if you try to + re-install the printer). To really get rid of the Adobe driver + files on the clients, open the "Printers" folder (possibly via + "Start --> Settings --> Control Panel --> Printers"), right-click + onto the folder background and select "Server Properties". A + new dialog opens; select the "Drivers" tab; on the list select + the driver you want to delete and click on the "Delete" button. + (This will only work if there is no single printer left which + uses that particular driver -- you need to "delete" all printers + using this driver in the "Printers" folder first...) + +NOTE 4: Once you have successfully downloaded the CUPS PostScript driver + to a client, you can easily switch all printers to this one + by proceeding as described elsewhere in the "Samba HOWTO + Collection" to change a driver for an existing printer.... + + +What are the benefits with the "CUPS PostScript driver for Windows NT/2k/XP" +as compared to the Adobe drivers? + 9 +* no hassle with the Adobe EULA; no hassle with the question "where do I + get the ADOBE*.* driver files from?" + +* the Adobe drivers (depending on the printer PPD associated with them) + often put a PJL header in front of the core PostScript part of the print + file (thus the file starts with "<1B>%-12345X" or "%-12345X" + instead of "%!PS"). This leads to the CUPS daemon autotyping the + arriving file as a print-ready file, not requiring a pass thru the + "pstops" filter (to speak more technical, it is not regarded as the + generic MIME type "application/postscript", but as the more special + MIME type "application/cups.vnd-postscript"), which therefore also + leads to the page accounting in "/var/log/cups/page_log" not receiving + the exact mumber of pages; instead the dummy page number of "1" is + logged in a standard setup...) + +* the Adobe driver has more options to "mis-configure" the PostScript + generated by it (like setting it inadvertedly to "Optimize for Speed", + instead of "Optimize for Portability", which could lead to CUPS being + unable to process it....) + +* the CUPS PostScript driver output sent by Windows clients to the CUPS + server will be guaranteed to be auto-typed as generic MIME type + "application/postscript", thusly passing thru the CUPS "pstops" filter + and logging the correct number of pages in the page_log for accounting + and quota purposes... + +* the CUPS PostScript driver supports the sending of additional print + options by the Win NT/2k/XP clients, such as naming the CUPS standard + banner pages (or the custom ones, should they be installed at the time + of driver download), using the CUPS "page-label" option, setting a + job-priority and setting the scheduled time of printing (with the option + to support additional useful IPP job attributes in the future). + +* the CUPS PostScript driver supports the inclusion of the new + "*cupsJobTicket" comments at the beginnig of the PostScript file (which + could be used in the future for all sort of beneficial extensions on + the CUPS side, but which will not disturb any other application as those + will regard it as a comment and simply ignore it). + +* the CUPS PostScript driver will be the heart of the fully fledged CUPS + IPP client for Windows NT/2k/XP to be released soon (probably alongside + the first Beta release for CUPS 1.2). + + + + + +Advanced Postscript Printing from MS Windows + + +* Let the Windows Clients use a PostScript driver, to produce + PostScript as their print output sent towards the Samba print + server (just like any Linux or Unix Client would also use + PostScript to send to the server...) + +* make the Unix printing subsystem which is underneath Samba + convert the incoming PostScript files to the native print + format of the target printers (would likely be PCL? + I understand you have mainly HP models?) + +* You're afraid, that this would just mean a *Generic* PostScript + driver for the clients? With no Simplex/Duplex selection, + no paper tray choice? But you need them to be able to set up + their jobs, ringing all the bells and whistles of the printers? + + --> Not possible with traditional spooling systems! + + --> But perfectly supported by CUPS (which uses "PPD" files to + describe how to control the print options for PostScript and + non-PostScript devices alike... + + CUPS PPDs are working perfectly on Windows + clients who use Adobe PostScript drivers (or the new CUPS + PostScript driver for Windows NT/2K/XP). Clients can use + them to setup the job to their liking and CUPS will use + the received job options to make the (PCL-, ESC/P- or + PostScript-) printer behave as required. + +* You want to have the additional benefit of page count logging + and accounting? In this case the CUPS PostScript driver + is the best choice (better than the Adobe one). + +* You want to make the drivers downloadable for the clients? + "cupsaddsmb" is your friend. It will setup the [print$] + share on the Samba host to be ready to serve the clients + for a "point and print" driver installation... + +"What strings are attached?", I hear you asking... + +You are right, there are some. But, given the sheer CPU power +you can buy nowadays in German supermarkets, these can be +overcome easily. + +The strings: Well, if the +CUPS/Samba side will have to print a *lot* onto 40 printers +serving 500 users, you probably will need to set up a second +server (which can do automatic load balancing with the first +one, plus a degree of fail-over mechanism). Converting the +incoming PostScript jobs, "interpreting" them for +non-PostScript printers, amounts to the work of a "RIP" +(Raster Image Processor) done in software. This requires +more CPU and RAM than for the mere "raw spooling" task +your current setup is solving... It all depends on the +avarage and peak printing load the server should be +able to handle.... + + + + + +Auto-Deletion of CUPS spool files + + +Samba print files pass thru 2 +different "spool" directories. Once the incoming directory +managed by Samba, (set f.e. in the "path = /var/spool/samba" +directive in the [printers] section of "smb.conf"). Second is +the spool directory of your UNIX print subsystem. For CUPS it is +normally "/var/spool/cups/", as set by the cupsd.conf directive +"RequestRoot /var/spool/cups". + +I am not sure, which one of your directories keeps the files. + From what you say, it is most likely the Samba part. + +For the CUPS part, you may want to consult: + + http://localhost:631/sam.html#PreserveJobFiles and + http://localhost:631/sam.html#PreserveJobHistory and + http://localhost:631/sam.html#MaxJobs + +There are the settings described for your CUPS daemon, which +could lead to completed job files not being deleted. + +"PreserveJobHistory Yes" -- keeps some details of jobs in +cupsd's mind (well it keeps the "c12345", "c12346" etc. files +in the CUPS spool directory, which do a similar job as the +old-fashioned BSD-LPD control files). This is set to "Yes" +as a default. + +"PreserveJobFiles Yes" -- keeps the job files themselves in +cupsd's mind (well it keeps the "d12345", "d12346" etc. files +in the CUPS spool directory...). This is set to "No" as the +CUPS default. + +"MaxJobs 500" -- this directive controls the maximum number +of jobs that are kept in memory. Once the number of jobs +reaches the limit, the oldest completed job is automatically +purged from the system to make room for the new one. If all +of the known jobs are still pending or active then the new +job will be rejected. Setting the maximum to 0 disables this +functionality. The default setting is 0. + +(There are also additional settings for "MaxJobsPerUser" and +"MaxJobsPerPrinter"...) + +For everything to work as announced, you need to have three +things: + + * a Samba-smbd which is compiled against "libcups" (Check + on Linux by running "ldd `which smbd`") + + * a Samba-smb.conf setting of "printing = cups" + + * another Samba-smb.conf setting of "printcap = cups" + +Note, that in this case all other manually set printing-related +commands (like "print command", "lpq command", "lprm command", +"lppause command" or "lpresume command") are ignored and they +should normally have no influence what-so-ever on your printing. + +If you want to do things manually, replace the "printing = cups" +by "printing = bsd". Then your manually set commands may work +(haven't tested this), and a "print command = lp -d %P %s; rm %s" +may do what you need. + +You forgot to mention the CUPS version you're using. If you did +set things up as described in the man pages, then the Samba +spool files should be deleted. Otherwise it may be a bug. On +the CUPS side, you can control the behaviour as described +above. +If you have more problems, post the output of these commands: + + grep -v ^# /etc/cups/cupsd.conf | grep -v ^$ + grep -v ^# /etc/samba/smb.conf | grep -v ^$ | grep -v "^;" + +(adapt paths as needed). These commands sanitize the files +and cut out the empty lines and lines with comments, providing +the "naked settings" in a compact way. + + diff --git a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml index c0be81d989..53dae21775 100644 --- a/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml +++ b/docs/docbook/projdoc/Samba-PDC-HOWTO.sgml @@ -13,13 +13,18 @@ Samba Team
dbannon@samba.org
+ John HTerpstra + + Samba Team +
jht@samba.org
+ (26 Apr 2001) -Samba as a NT4 or Win2k Primary Domain Controller +Samba as an NT4 or Win2k Primary Domain Controller @@ -37,8 +42,7 @@ that you are comfortable with configuring basic files services in smb.conf and how to enable and administer password encryption in Samba. Theses two topics are covered in the smb.conf(5) -manpage and the Encryption chapter -of this HOWTO Collection. +manpage. @@ -56,46 +60,28 @@ of this HOWTO Collection. Background - -Author's Note: This document is a combination -of David Bannon's "Samba 2.2 PDC HOWTO" and "Samba NT Domain FAQ". -Both documents are superseded by this one. - - - - -Versions of Samba prior to release 2.2 had marginal capabilities to act -as a Windows NT 4.0 Primary Domain Controller -Primary Domain Controller -(PDC). With Samba 2.2.0, we are proud to announce official support for -Windows NT 4.0-style domain logons from Windows NT 4.0 and Windows -2000 clients. This article outlines the steps -necessary for configuring Samba as a PDC. It is necessary to have a -working Samba server prior to implementing the PDC functionality. If -you have not followed the steps outlined in UNIX_INSTALL.html, please make sure -that your server is configured correctly before proceeding. Another -good resource in the smb.conf(5) man -page. The following functionality should work in 2.2: +This article outlines the steps necessary for configuring Samba as a PDC. +It is necessary to have a working Samba server prior to implementing the +PDC functionality. - domain logons for Windows NT 4.0/2000 clients. + domain logons for Windows NT 4.0 / 200x / XP Professional clients. - placing a Windows 9x client in user level security + placing Windows 9x / Me clients in user level security retrieving a list of users and groups from a Samba PDC to - Windows 9x/NT/2000 clients + Windows 9x / Me / NT / 200x / XP Professional clients - roving (roaming) user profiles + roaming user profiles @@ -105,7 +91,7 @@ page. The following functionality should work in 2.2: -The following pieces of functionality are not included in the 2.2 release: +The following functionalities are new to the Samba 3.0 release: @@ -113,15 +99,21 @@ The following pieces of functionality are not included in the 2.2 release: Windows NT 4 domain trusts + + Adding users via the User Manager for Domains + + + + +The following functionalities are NOT provided by Samba 3.0: + + + SAM replication with Windows NT 4.0 Domain Controllers (i.e. a Samba PDC and a Windows NT BDC or vice versa) - - Adding users via the User Manager for Domains - - Acting as a Windows 2000 Domain Controller (i.e. Kerberos and Active Directory) @@ -129,16 +121,21 @@ The following pieces of functionality are not included in the 2.2 release: -Please note that Windows 9x clients are not true members of a domain +Please note that Windows 9x / Me / XP Home clients are not true members of a domain for reasons outlined in this article. Therefore the protocol for support Windows 9x-style domain logons is completely different -from NT4 domain logons and has been officially supported for some +from NT4 / Win2k type domain logons and has been officially supported for some time. + +MS Windows XP Home edition is NOT able to join a domain and does not permit +the use of domain logons. + + -Implementing a Samba PDC can basically be divided into 2 broad +Implementing a Samba PDC can basically be divided into 3 broad steps. @@ -148,8 +145,11 @@ steps. - Creating machine trust accounts and joining clients - to the domain + Creating machine trust accounts and joining clients to the domain + + + + Adding and managing domain user accounts @@ -157,7 +157,7 @@ steps. There are other minor details such as user profiles, system policies, etc... However, these are not necessarily specific to a Samba PDC as much as they are related to Windows NT networking -concepts. They will be mentioned only briefly here. +concepts. @@ -174,11 +174,10 @@ concepts. They will be mentioned only briefly here. The first step in creating a working Samba PDC is to -understand the parameters necessary in smb.conf. I will not -attempt to re-explain the parameters here as they are more that -adequately covered in the smb.conf -man page. For convenience, the parameters have been -linked with the actual smb.conf description. +understand the parameters necessary in smb.conf. Here we +attempt to explain the parameters that are covered in + the smb.conf +man page. @@ -209,8 +208,7 @@ Here is an example smb.conf for acting as a PDC: ; where to store user profiles? logon path = \\%N\profiles\%u - ; where is a user's home directory and where should it - ; be mounted at? + ; where is a user's home directory and where should it be mounted at? logon drive = H: logon home = \\homeserver\%u @@ -256,20 +254,16 @@ There are a couple of points to emphasize in the above configuration. -As Samba 2.2 does not offer a complete implementation of group mapping +Samba 3.0 offers a complete implementation of group mapping between Windows NT groups and Unix groups (this is really quite -complicated to explain in a short space), you should refer to the -domain admin -group smb.conf parameter for information of creating "Domain -Admins" style accounts. +complicated to explain in a short space). -Creating Machine Trust Accounts and Joining Clients to the -Domain +Creating Machine Trust Accounts and Joining Clients to the Domain A machine trust account is a Samba account that is used to @@ -282,15 +276,65 @@ The password of a machine trust account acts as the shared secret for secure communication with the Domain Controller. This is a security feature to prevent an unauthorized machine with the same NetBIOS name from joining the domain and gaining access to domain user/group -accounts. Windows NT and 2000 clients use machine trust accounts, but -Windows 9x clients do not. Hence, a Windows 9x client is never a true -member of a domain because it does not possess a machine trust -account, and thus has no shared secret with the domain controller. +accounts. Windows NT, 200x, XP Professional clients use machine trust +accounts, but Windows 9x / Me / XP Home clients do not. Hence, a +Windows 9x / Me / XP Home client is never a true member of a domain +because it does not possess a machine trust account, and thus has no +shared secret with the domain controller. A Windows PDC stores each machine trust account in the Windows -Registry. A Samba PDC, however, stores each machine trust account -in two parts, as follows: +Registry. A Samba-3 PDC also has to stoe machine trust account information +in a suitable back-end data store. With Samba-3 there can be multiple back-ends +for this including: + + + + + smbpaswd - the plain ascii file stored used by + earlier versions of Samba. This file configuration option requires + a Unix/Linux system account for EVERY entry (ie: both for user and for + machine accounts). This file will be located in the private + directory (default is /usr/local/samba/lib/private or on linux /etc/samba). + + + + smbpasswd_nua - This file is independant of the + system wide user accounts. The use of this back-end option requires + specification of the "non unix account range" option also. It is called + smbpasswd and will be located in the private directory. + + + + tdbsam - a binary database backend that will be + stored in the private directory in a file called + passwd.tdb. The key benefit of this binary format + file is that it can store binary objects that can not be accomodated + in the traditional plain text smbpasswd file. + + + + tdbsam_nua like the smbpasswd_nua option above, this + file allows the creation of arbitrary user and machine accounts without + requiring that account to be added to the system (/etc/passwd) file. It + too requires the specification of the "non unix account range" option + in the [globals] section of the smb.conf file. + + + + ldapsam - An LDAP based back-end. Permits the + LDAP server to be specified. eg: ldap://localhost or ldap://frodo.murphy.com + + + + ldapsam_nua - LDAP based back-end with no unix + account requirement, like smbpasswd_nua and tdbsam_nua above. + + + + +A Samba PDC, however, stores each machine trust account in two parts, +as follows: A Samba account, stored in the same location as user diff --git a/docs/docbook/projdoc/ServerType.sgml b/docs/docbook/projdoc/ServerType.sgml new file mode 100644 index 0000000000..65544572b7 --- /dev/null +++ b/docs/docbook/projdoc/ServerType.sgml @@ -0,0 +1,140 @@ + + + + John HTerpstra + + Samba Team +
jht@samba.org
+ + + + +Nomenclature of Server Types + +Adminstrators of Microsoft networks often refer to there being three +different type of servers: + + + Stand Alone Server + Domain Member Server + Domain Controller + + Primary Domain Controller + Backup Domain Controller + + + + +A network administrator who is familiar with these terms and who +wishes to migrate to or use Samba will want to know what these terms mean +within a Samba context. + + +Stand Alone Server + + +The term stand alone server means that the server +will provide local authentication and access control for all resources +that are available from it. In general this means that there will be a +local user database. In more technical terms, it means that resources +on the machine will either be made available in either SHARE mode or in +USER mode. SHARE mode and USER mode security are documented under +discussions regarding "security mode". The smb.conf configuration parameters +that control security mode are: "security = user" and "security = share". + + + +Samba tends to blur the distinction a little in respect of what is +a stand alone server. This is because the authentication database may be +local or on a remote server, even if from the samba protocol perspective +the samba server is NOT a member of a domain security context. + + + +Through the use of PAM (Pluggable Authentication Modules) and nsswitch +(the name service switcher) the source of authentication may reside on +another server. We would be inclined to call this the authentication server. +This means that the samba server may use the local Unix/Linux system +password database (/etc/passwd or /etc/shadow), may use a local smbpasswd +file (/etc/samba/smbpasswd or /usr/local/samba/lib/private/smbpasswd), or +may use an LDAP back end, or even via PAM and Winbind another CIFS/SMB +server for authentication. + + + + + +Domain Member Server + + +This mode of server operation involves the samba machine being made a member +of a domain security context. This means by definition that all user authentication +will be done from a centrally defined authentication regime. The authentication +regime may come from an NT3/4 style (old domain technology) server, or it may be +provided from an Active Directory server (ADS) running on MS Windows 2000 or later. +>/para> + + +Of course it should be clear that the authentication back end itself could be from any +distributed directory architecture server that is supported by Samba. This can be +LDAP (from OpenLDAP), or Sun's iPlanet, of NetWare Directory Server, etc. + + + +Please refer to the section on Howto configure Samba as a Primary Domain Controller +and for more information regarding how to create a domain machine account for a +domain member server as well as for information regading how to enable the samba +domain member machine to join the domain and to be fully trusted by it. + + + + + +Domain Controller + + +Over the years public perceptions of what Domain Control really is has taken on an +almost mystical nature. Before we branch into a brief overview of what Domain Control +is the following types of controller are known: + + + +Domain Controller Types + + + Primary Domain Controller + Backup Domain Controller + ADS Domain Controller + + + +The Primary Domain Controller or PDC plays an important role in the MS +Windows NT3 and NT4 Domain Control architecture, but not in the manner that so many +expect. The PDC seeds the Domain Control database (a part of the Windows registry) and +it plays a key part in synchronisation of the domain authentication database. + + + +New to Samba-3.0.0 is the ability to use a back-end file that holds the same type of data as +the NT4 style SAM (Security Account Manager) database (one of the registry files). +The samba-3.0.0 SAM can be specified via the smb.conf file parameter "passwd backend" and +valid options include smbpasswd tdbsam ldapsam nisplussam plugin unixsam. +The smbpasswd, tdbsam and ldapsam options can have a "_nua" suffix to indicate that No Unix +Accounts need to be created. In other words, the Samba SAM will be independant of Unix/Linux +system accounts, provided a uid range is defined from which SAM accounts can be created. + + + +The Backup Domain Controller or BDC plays a key role in servicing network +authentication requests. The BDC is biased to answer logon requests so that on a network segment +that has a BDC and a PDC the BDC will be most likely to service network logon requests. The PDC will +answer network logon requests when the BDC is too busy (high load). A BDC can be promoted to +a PDC. If the PDC is on line at the time that the BDC is promoted to PDC the previous PDC is +automatically demoted to a BDC. + + + +At this time Samba is NOT capable of acting as an ADS Domain Controller. + + + diff --git a/docs/docbook/projdoc/passdb.sgml b/docs/docbook/projdoc/passdb.sgml index 222b4010ab..fa2d75bd34 100644 --- a/docs/docbook/projdoc/passdb.sgml +++ b/docs/docbook/projdoc/passdb.sgml @@ -30,6 +30,16 @@ + + John HTerpstra + + Samba Team +
+ jht@samba.org +
+ + + February 2003 @@ -104,6 +114,10 @@ Other Microsoft operating systems which also exhibit this behavior includes + These versions of MS Windows do not support full domain + security protocols, although they may log onto a domain environment. + Of these Only MS Windows XP Home does NOT support domain logons. + MS DOS Network client 3.0 with the basic network redirector installed @@ -112,8 +126,25 @@ update installed Windows 98 [se] + + Windows Me + + Windows XP Home + + + The following versions of MS Windows fully support domain + security protocols. + + + Windows NT 3.5x + + Windows NT 4.0 - Windows 2000 + Windows 2000 Professional + + Windows 200x Server/Advanced Server + + Windows XP Professional Note :All current release of @@ -121,23 +152,36 @@ SMB Challenge/Response mechanism described here. Enabling clear text authentication does not disable the ability of the client to participate in encrypted authentication. + + + MS Windows clients will cache the encrypted password alone. + Even when plain text passwords are re-enabled, through the appropriate + registry change, the plain text password is NEVER cached. This means that + in the event that a network connections should become disconnected (broken) + only the cached (encrypted) password will be sent to the resource server + to affect a auto-reconnect. If the resource server does not support encrypted + passwords the auto-reconnect will fail. USE OF ENCRYPTED PASSWORDS + IS STRONGLY ADVISED. Advantages of SMB Encryption - plain text passwords are not passed across + Plain text passwords are not passed across the network. Someone using a network sniffer cannot just record passwords going to the SMB server. WinNT doesn't like talking to a server - that isn't using SMB encrypted passwords. It will refuse + that SM not support encrypted passwords. It will refuse to browse the server if the server is also in user level security mode. It will insist on prompting the user for the password on each connection, which is very annoying. The only things you can do to stop this is to use SMB encryption. + + Encrypted password support allows auto-matic share + (resource) reconnects. @@ -146,16 +190,15 @@ Advantages of non-encrypted passwords - plain text passwords are not kept - on disk. + Plain text passwords are not kept + on disk, and are NOT cached in memory. - uses same password file as other unix + Uses same password file as other unix services such as login and ftp - you are probably already using other - services (such as telnet and ftp) which send plain text - passwords over the net, so sending them for SMB isn't - such a big deal. + Use of other services (such as telnet and ftp) which + send plain text passwords over the net, so sending them for SMB + isn't such a big deal. @@ -166,8 +209,7 @@ The smbpasswd utility is a utility similar to the passwd or yppasswd programs. - It maintains the two 32 byte password fields - in the passdb backend. + It maintains the two 32 byte password fields in the passdb backend. smbpasswd works in a client-server mode where it contacts the local smbd to change the user's password on its @@ -352,11 +394,12 @@ the details of configuring these packages are beyond the scope of this document. Supported LDAP Servers -The LDAP samdb code in 2.2.3 has been developed and tested using the OpenLDAP -2.0 server and client libraries. The same code should be able to work with -Netscape's Directory Server and client SDK. However, due to lack of testing -so far, there are bound to be compile errors and bugs. These should not be -hard to fix. If you are so inclined, please be sure to forward all patches to +The LDAP samdb code in 2.2.3 (and later) has been developed and tested +using the OpenLDAP 2.0 server and client libraries. +The same code should be able to work with Netscape's Directory Server +and client SDK. However, due to lack of testing so far, there are bound +to be compile errors and bugs. These should not be hard to fix. +If you are so inclined, please be sure to forward all patches to samba-patches@samba.org and jerry@samba.org. diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml index c1662ee3bf..d06d86337d 100644 --- a/docs/docbook/projdoc/samba-doc.sgml +++ b/docs/docbook/projdoc/samba-doc.sgml @@ -5,6 +5,7 @@ + @@ -91,6 +92,7 @@ Samba can operate in various SMB networks. This part contains information on con for various environments. +&ServerType; &SECURITY-LEVEL; &Samba-PDC-HOWTO; &Samba-BDC-HOWTO; diff --git a/docs/docbook/projdoc/security_level.sgml b/docs/docbook/projdoc/security_level.sgml index e2d9cfbbaa..00dcc6e83b 100644 --- a/docs/docbook/projdoc/security_level.sgml +++ b/docs/docbook/projdoc/security_level.sgml @@ -9,7 +9,7 @@ -User and Share security level (for servers not in a domain) +Samba as Stand-Alone server (User and Share security level) A SMB server tells the client at startup what "security level" it is diff --git a/docs/docbook/projdoc/unicode.sgml b/docs/docbook/projdoc/unicode.sgml index a467a0d4e7..7d8f0a03be 100644 --- a/docs/docbook/projdoc/unicode.sgml +++ b/docs/docbook/projdoc/unicode.sgml @@ -2,10 +2,10 @@ JelmerVernooij - + Samba Team
jelmer@samba.org
- + 25 March 2003 @@ -18,8 +18,8 @@ Computers communicate in numbers. In texts, each number will be translated to a corresponding letter. The meaning that will be assigned -to a certain number depends on the character set(charset) - that is used. +to a certain number depends on the character set(charset) + that is used. A charset can be seen as a table that is used to translate numbers to letters. Not all computers use the same charset (there are charsets with German umlauts, Japanese characters, etc). Usually a charset contains @@ -64,7 +64,7 @@ samba knows of three kinds of character sets: unix charset This is the charset used internally by your operating system. - The default is ASCII, which is fine for most + The default is ASCII, which is fine for most systems. -- cgit From 872d55c8bf2fc3096c09d3304634d54ccf3d5b89 Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Thu, 27 Mar 2003 14:22:03 +0000 Subject: Tidy XML formating (This used to be commit f9515634f344f2408909d2398a7b585b91dca6ec) --- docs/docbook/global.ent | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/global.ent b/docs/docbook/global.ent index a3022ecfaa..018d29a6a8 100644 --- a/docs/docbook/global.ent +++ b/docs/docbook/global.ent @@ -165,10 +165,10 @@ password. --U|--user=username[&%;password] +-U|--user=username[%password] Sets the SMB username or username and password. -If &%;password is not specified, the user will be prompted. The +If %password is not specified, the user will be prompted. The client will first check the USER environment variable, then the LOGNAME variable and if either exists, the string is uppercased. If these environmental variables are not -- cgit From 5cd3d3f14ef56ff5f1d92aba0174649f3d368f66 Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Thu, 27 Mar 2003 15:27:19 +0000 Subject: Add new framework for smb.conf(5). Please read README before trying to compile. I will commit more meta-information updates during week-end. (This used to be commit 8d684dffab6a90b3d612a1aa2b2c457a2bc2e6ac) --- docs/docbook/smbdotconf/.cvsignore | 4 + docs/docbook/smbdotconf/README | 159 +++++ docs/docbook/smbdotconf/base/adsserver.xml | 15 + .../docbook/smbdotconf/base/bindinterfacesonly.xml | 66 ++ docs/docbook/smbdotconf/base/comment.xml | 14 + docs/docbook/smbdotconf/base/directory.xml | 5 + docs/docbook/smbdotconf/base/displaycharset.xml | 13 + docs/docbook/smbdotconf/base/doscharset.xml | 14 + docs/docbook/smbdotconf/base/interfaces.xml | 49 ++ docs/docbook/smbdotconf/base/netbiosaliases.xml | 17 + docs/docbook/smbdotconf/base/netbiosname.xml | 16 + docs/docbook/smbdotconf/base/netbiosscope.xml | 7 + docs/docbook/smbdotconf/base/path.xml | 27 + docs/docbook/smbdotconf/base/realm.xml | 12 + docs/docbook/smbdotconf/base/serverstring.xml | 22 + docs/docbook/smbdotconf/base/unixcharset.xml | 11 + docs/docbook/smbdotconf/base/workgroup.xml | 11 + docs/docbook/smbdotconf/browse/browsable.xml | 5 + docs/docbook/smbdotconf/browse/browseable.xml | 8 + docs/docbook/smbdotconf/browse/browselist.xml | 10 + docs/docbook/smbdotconf/browse/domainmaster.xml | 34 + .../docbook/smbdotconf/browse/enhancedbrowsing.xml | 24 + docs/docbook/smbdotconf/browse/lmannounce.xml | 24 + docs/docbook/smbdotconf/browse/lminterval.xml | 17 + docs/docbook/smbdotconf/browse/localmaster.xml | 18 + docs/docbook/smbdotconf/browse/oslevel.xml | 21 + docs/docbook/smbdotconf/browse/preferedmaster.xml | 6 + docs/docbook/smbdotconf/browse/preferredmaster.xml | 25 + .../smbdotconf/domain/machinepasswordtimeout.xml | 18 + docs/docbook/smbdotconf/expand-smb.conf.xsl | 74 +++ docs/docbook/smbdotconf/filename/casesensitive.xml | 7 + docs/docbook/smbdotconf/filename/casesignames.xml | 5 + docs/docbook/smbdotconf/filename/defaultcase.xml | 9 + .../smbdotconf/filename/deletevetofiles.xml | 25 + docs/docbook/smbdotconf/filename/hidedotfiles.xml | 7 + docs/docbook/smbdotconf/filename/hidefiles.xml | 35 ++ .../smbdotconf/filename/hidespecialfiles.xml | 10 + .../docbook/smbdotconf/filename/hideunreadable.xml | 8 + .../smbdotconf/filename/hideunwriteablefiles.xml | 10 + docs/docbook/smbdotconf/filename/manglecase.xml | 8 + docs/docbook/smbdotconf/filename/mangledmap.xml | 23 + docs/docbook/smbdotconf/filename/manglednames.xml | 58 ++ docs/docbook/smbdotconf/filename/mangledstack.xml | 23 + docs/docbook/smbdotconf/filename/mangleprefix.xml | 11 + docs/docbook/smbdotconf/filename/manglingchar.xml | 11 + .../docbook/smbdotconf/filename/manglingmethod.xml | 14 + docs/docbook/smbdotconf/filename/maparchive.xml | 17 + docs/docbook/smbdotconf/filename/maphidden.xml | 13 + docs/docbook/smbdotconf/filename/mapsystem.xml | 13 + docs/docbook/smbdotconf/filename/preservecase.xml | 13 + .../smbdotconf/filename/shortpreservecase.xml | 16 + docs/docbook/smbdotconf/filename/statcache.xml | 10 + docs/docbook/smbdotconf/filename/stripdot.xml | 9 + docs/docbook/smbdotconf/filename/vetofiles.xml | 46 ++ .../smbdotconf/filename/vetooplockfiles.xml | 24 + docs/docbook/smbdotconf/generate-context.xsl | 56 ++ docs/docbook/smbdotconf/generate-file-list.sh | 8 + docs/docbook/smbdotconf/ldap/ldapadmindn.xml | 13 + docs/docbook/smbdotconf/ldap/ldapdeletedn.xml | 10 + .../docbook/smbdotconf/ldap/ldapdelonlysamattr.xml | 6 + docs/docbook/smbdotconf/ldap/ldapfilter.xml | 12 + docs/docbook/smbdotconf/ldap/ldapmachinesuffix.xml | 11 + docs/docbook/smbdotconf/ldap/ldappasswdsync.xml | 23 + docs/docbook/smbdotconf/ldap/ldapport.xml | 20 + docs/docbook/smbdotconf/ldap/ldapserver.xml | 15 + docs/docbook/smbdotconf/ldap/ldapssl.xml | 30 + docs/docbook/smbdotconf/ldap/ldapsuffix.xml | 8 + docs/docbook/smbdotconf/ldap/ldaptrustids.xml | 18 + docs/docbook/smbdotconf/ldap/ldapusersuffix.xml | 10 + docs/docbook/smbdotconf/locking/blockinglocks.xml | 22 + docs/docbook/smbdotconf/locking/cscpolicy.xml | 18 + docs/docbook/smbdotconf/locking/fakeoplocks.xml | 27 + docs/docbook/smbdotconf/locking/kerneloplocks.xml | 24 + docs/docbook/smbdotconf/locking/level2oplocks.xml | 39 ++ docs/docbook/smbdotconf/locking/locking.xml | 25 + docs/docbook/smbdotconf/locking/lockspincount.xml | 15 + docs/docbook/smbdotconf/locking/lockspintime.xml | 11 + .../smbdotconf/locking/oplockbreakwaittime.xml | 16 + .../smbdotconf/locking/oplockcontentionlimit.xml | 19 + docs/docbook/smbdotconf/locking/oplocks.xml | 27 + docs/docbook/smbdotconf/locking/posixlocking.xml | 14 + docs/docbook/smbdotconf/locking/sharemodes.xml | 26 + docs/docbook/smbdotconf/locking/strictlocking.xml | 17 + .../smbdotconf/logging/debughirestimestamp.xml | 14 + docs/docbook/smbdotconf/logging/debuglevel.xml | 6 + docs/docbook/smbdotconf/logging/debugpid.xml | 13 + docs/docbook/smbdotconf/logging/debugtimestamp.xml | 10 + docs/docbook/smbdotconf/logging/debuguid.xml | 13 + docs/docbook/smbdotconf/logging/logfile.xml | 11 + docs/docbook/smbdotconf/logging/loglevel.xml | 15 + docs/docbook/smbdotconf/logging/maxlogsize.xml | 13 + docs/docbook/smbdotconf/logging/syslog.xml | 17 + docs/docbook/smbdotconf/logging/syslogonly.xml | 9 + docs/docbook/smbdotconf/logging/timestamplogs.xml | 6 + .../smbdotconf/logon/abortshutdownscript.xml | 13 + docs/docbook/smbdotconf/logon/addgroupscript.xml | 14 + docs/docbook/smbdotconf/logon/addmachinescript.xml | 18 + docs/docbook/smbdotconf/logon/adduserscript.xml | 49 ++ .../smbdotconf/logon/addusertogroupscript.xml | 16 + .../docbook/smbdotconf/logon/deletegroupscript.xml | 8 + .../smbdotconf/logon/deleteuserfromgroupscript.xml | 16 + docs/docbook/smbdotconf/logon/deleteuserscript.xml | 21 + docs/docbook/smbdotconf/logon/domainlogons.xml | 12 + docs/docbook/smbdotconf/logon/logondrive.xml | 13 + docs/docbook/smbdotconf/logon/logonhome.xml | 40 ++ docs/docbook/smbdotconf/logon/logonpath.xml | 45 ++ docs/docbook/smbdotconf/logon/logonscript.xml | 39 ++ docs/docbook/smbdotconf/logon/shutdownscript.xml | 42 ++ docs/docbook/smbdotconf/man.xsl | 159 +++++ docs/docbook/smbdotconf/misc/addsharecommand.xml | 51 ++ docs/docbook/smbdotconf/misc/autoservices.xml | 6 + docs/docbook/smbdotconf/misc/available.xml | 11 + .../docbook/smbdotconf/misc/changesharecommand.xml | 50 ++ docs/docbook/smbdotconf/misc/configfile.xml | 21 + docs/docbook/smbdotconf/misc/copy.xml | 15 + docs/docbook/smbdotconf/misc/default.xml | 5 + docs/docbook/smbdotconf/misc/defaultservice.xml | 36 ++ docs/docbook/smbdotconf/misc/deletereadonly.xml | 11 + .../docbook/smbdotconf/misc/deletesharecommand.xml | 44 ++ docs/docbook/smbdotconf/misc/dfreecommand.xml | 50 ++ docs/docbook/smbdotconf/misc/dontdescend.xml | 18 + docs/docbook/smbdotconf/misc/dosfilemode.xml | 16 + .../smbdotconf/misc/dosfiletimeresolution.xml | 23 + docs/docbook/smbdotconf/misc/dosfiletimes.xml | 14 + docs/docbook/smbdotconf/misc/exec.xml | 5 + .../smbdotconf/misc/fakedirectorycreatetimes.xml | 31 + docs/docbook/smbdotconf/misc/followsymlinks.xml | 18 + docs/docbook/smbdotconf/misc/fstype.xml | 14 + docs/docbook/smbdotconf/misc/hidelocalusers.xml | 7 + docs/docbook/smbdotconf/misc/homedirmap.xml | 28 + docs/docbook/smbdotconf/misc/include.xml | 14 + docs/docbook/smbdotconf/misc/lockdir.xml | 5 + docs/docbook/smbdotconf/misc/lockdirectory.xml | 11 + docs/docbook/smbdotconf/misc/magicoutput.xml | 17 + docs/docbook/smbdotconf/misc/magicscript.xml | 28 + docs/docbook/smbdotconf/misc/messagecommand.xml | 65 ++ docs/docbook/smbdotconf/misc/nishomedir.xml | 30 + docs/docbook/smbdotconf/misc/panicaction.xml | 12 + docs/docbook/smbdotconf/misc/piddirectory.xml | 9 + docs/docbook/smbdotconf/misc/postexec.xml | 22 + docs/docbook/smbdotconf/misc/preexec.xml | 23 + docs/docbook/smbdotconf/misc/preexecclose.xml | 9 + docs/docbook/smbdotconf/misc/preload.xml | 16 + docs/docbook/smbdotconf/misc/remoteannounce.xml | 32 + docs/docbook/smbdotconf/misc/remotebrowsesync.xml | 33 + docs/docbook/smbdotconf/misc/rootpostexec.xml | 14 + docs/docbook/smbdotconf/misc/rootpreexec.xml | 15 + docs/docbook/smbdotconf/misc/rootpreexecclose.xml | 12 + docs/docbook/smbdotconf/misc/setdirectory.xml | 13 + docs/docbook/smbdotconf/misc/socketaddress.xml | 14 + docs/docbook/smbdotconf/misc/sourceenvironment.xml | 23 + docs/docbook/smbdotconf/misc/timeoffset.xml | 11 + docs/docbook/smbdotconf/misc/utmp.xml | 21 + docs/docbook/smbdotconf/misc/utmpdirectory.xml | 16 + docs/docbook/smbdotconf/misc/volume.xml | 9 + docs/docbook/smbdotconf/misc/widelinks.xml | 15 + docs/docbook/smbdotconf/misc/wtmpdirectory.xml | 20 + .../smbdotconf/printing/addprintercommand.xml | 60 ++ .../docbook/smbdotconf/printing/defaultdevmode.xml | 34 + .../smbdotconf/printing/deleteprintercommand.xml | 35 ++ .../docbook/smbdotconf/printing/disablespoolss.xml | 20 + .../smbdotconf/printing/enumportscommand.xml | 22 + docs/docbook/smbdotconf/printing/loadprinters.xml | 9 + .../docbook/smbdotconf/printing/lppausecommand.xml | 41 ++ docs/docbook/smbdotconf/printing/lpqcachetime.xml | 26 + docs/docbook/smbdotconf/printing/lpqcommand.xml | 41 ++ .../smbdotconf/printing/lpresumecommand.xml | 37 ++ docs/docbook/smbdotconf/printing/lprmcommand.xml | 27 + docs/docbook/smbdotconf/printing/maxprintjobs.xml | 14 + docs/docbook/smbdotconf/printing/os2drivermap.xml | 22 + docs/docbook/smbdotconf/printing/printable.xml | 15 + docs/docbook/smbdotconf/printing/printcap.xml | 6 + docs/docbook/smbdotconf/printing/printcapname.xml | 47 ++ docs/docbook/smbdotconf/printing/printcommand.xml | 86 +++ docs/docbook/smbdotconf/printing/printer.xml | 6 + docs/docbook/smbdotconf/printing/printername.xml | 15 + docs/docbook/smbdotconf/printing/printing.xml | 26 + docs/docbook/smbdotconf/printing/printok.xml | 6 + .../smbdotconf/printing/queuepausecommand.xml | 26 + .../smbdotconf/printing/queueresumecommand.xml | 31 + .../smbdotconf/printing/showaddprinterwizard.xml | 31 + .../docbook/smbdotconf/printing/totalprintjobs.xml | 18 + .../smbdotconf/printing/useclientdriver.xml | 35 ++ docs/docbook/smbdotconf/process-all.sh | 15 + docs/docbook/smbdotconf/protocol/announceas.xml | 18 + .../smbdotconf/protocol/announceversion.xml | 12 + .../docbook/smbdotconf/protocol/disablenetbios.xml | 14 + .../docbook/smbdotconf/protocol/largereadwrite.xml | 15 + docs/docbook/smbdotconf/protocol/maxmux.xml | 9 + docs/docbook/smbdotconf/protocol/maxprotocol.xml | 35 ++ docs/docbook/smbdotconf/protocol/maxttl.xml | 12 + docs/docbook/smbdotconf/protocol/maxwinsttl.xml | 15 + docs/docbook/smbdotconf/protocol/maxxmit.xml | 12 + docs/docbook/smbdotconf/protocol/minprotocol.xml | 20 + docs/docbook/smbdotconf/protocol/minwinsttl.xml | 13 + .../smbdotconf/protocol/nameresolveorder.xml | 47 ++ docs/docbook/smbdotconf/protocol/ntaclsupport.xml | 11 + docs/docbook/smbdotconf/protocol/ntpipesupport.xml | 12 + .../smbdotconf/protocol/ntstatussupport.xml | 14 + docs/docbook/smbdotconf/protocol/protocol.xml | 5 + docs/docbook/smbdotconf/protocol/readbmpx.xml | 10 + docs/docbook/smbdotconf/protocol/readraw.xml | 21 + docs/docbook/smbdotconf/protocol/smbports.xml | 10 + docs/docbook/smbdotconf/protocol/timeserver.xml | 9 + docs/docbook/smbdotconf/protocol/unicode.xml | 11 + .../docbook/smbdotconf/protocol/unixextensions.xml | 12 + docs/docbook/smbdotconf/protocol/usespnego.xml | 11 + docs/docbook/smbdotconf/protocol/writeraw.xml | 9 + docs/docbook/smbdotconf/security/adminusers.xml | 15 + .../smbdotconf/security/algorithmicridbase.xml | 22 + docs/docbook/smbdotconf/security/allowhosts.xml | 5 + .../smbdotconf/security/allowtrusteddomains.xml | 22 + docs/docbook/smbdotconf/security/authmethods.xml | 16 + docs/docbook/smbdotconf/security/createmask.xml | 39 ++ docs/docbook/smbdotconf/security/createmode.xml | 5 + docs/docbook/smbdotconf/security/denyhosts.xml | 5 + docs/docbook/smbdotconf/security/directorymask.xml | 43 ++ docs/docbook/smbdotconf/security/directorymode.xml | 5 + .../smbdotconf/security/directorysecuritymask.xml | 32 + .../smbdotconf/security/encryptpasswords.xml | 21 + .../smbdotconf/security/forcecreatemode.xml | 25 + .../smbdotconf/security/forcedirectorymode.xml | 26 + .../security/forcedirectorysecuritymode.xml | 32 + docs/docbook/smbdotconf/security/forcegroup.xml | 35 ++ .../smbdotconf/security/forcesecuritymode.xml | 33 + docs/docbook/smbdotconf/security/forceuser.xml | 25 + docs/docbook/smbdotconf/security/group.xml | 5 + docs/docbook/smbdotconf/security/guestaccount.xml | 27 + docs/docbook/smbdotconf/security/guestok.xml | 17 + docs/docbook/smbdotconf/security/guestonly.xml | 13 + docs/docbook/smbdotconf/security/hostsallow.xml | 60 ++ docs/docbook/smbdotconf/security/hostsdeny.xml | 14 + docs/docbook/smbdotconf/security/hostsequiv.xml | 26 + docs/docbook/smbdotconf/security/inheritacls.xml | 14 + .../smbdotconf/security/inheritpermissions.xml | 36 ++ docs/docbook/smbdotconf/security/invalidusers.xml | 33 + docs/docbook/smbdotconf/security/lanmanauth.xml | 11 + docs/docbook/smbdotconf/security/maptoguest.xml | 53 ++ .../smbdotconf/security/minpasswdlength.xml | 6 + .../smbdotconf/security/minpasswordlength.xml | 14 + .../smbdotconf/security/nonunixaccountrange.xml | 21 + docs/docbook/smbdotconf/security/ntlmauth.xml | 16 + docs/docbook/smbdotconf/security/nullpasswords.xml | 11 + .../smbdotconf/security/obeypamrestrictions.xml | 15 + docs/docbook/smbdotconf/security/onlyguest.xml | 6 + docs/docbook/smbdotconf/security/onlyuser.xml | 24 + .../smbdotconf/security/pampasswordchange.xml | 16 + docs/docbook/smbdotconf/security/passdbbackend.xml | 91 +++ docs/docbook/smbdotconf/security/passwdchat.xml | 58 ++ .../smbdotconf/security/passwdchatdebug.xml | 25 + docs/docbook/smbdotconf/security/passwdprogram.xml | 35 ++ docs/docbook/smbdotconf/security/passwordlevel.xml | 40 ++ .../docbook/smbdotconf/security/passwordserver.xml | 92 +++ docs/docbook/smbdotconf/security/printeradmin.xml | 12 + docs/docbook/smbdotconf/security/privatedir.xml | 10 + docs/docbook/smbdotconf/security/public.xml | 6 + docs/docbook/smbdotconf/security/readlist.xml | 17 + docs/docbook/smbdotconf/security/readonly.xml | 16 + .../smbdotconf/security/restrictanonymous.xml | 10 + docs/docbook/smbdotconf/security/root.xml | 6 + docs/docbook/smbdotconf/security/rootdir.xml | 6 + docs/docbook/smbdotconf/security/rootdirectory.xml | 28 + docs/docbook/smbdotconf/security/security.xml | 237 +++++++ docs/docbook/smbdotconf/security/securitymask.xml | 33 + docs/docbook/smbdotconf/security/smbpasswdfile.xml | 13 + .../smbdotconf/security/unixpasswordsync.xml | 18 + .../smbdotconf/security/updateencrypted.xml | 28 + docs/docbook/smbdotconf/security/user.xml | 6 + docs/docbook/smbdotconf/security/username.xml | 62 ++ docs/docbook/smbdotconf/security/usernamelevel.xml | 20 + docs/docbook/smbdotconf/security/usernamemap.xml | 90 +++ docs/docbook/smbdotconf/security/users.xml | 6 + docs/docbook/smbdotconf/security/validusers.xml | 23 + docs/docbook/smbdotconf/security/writable.xml | 6 + docs/docbook/smbdotconf/security/writeable.xml | 6 + docs/docbook/smbdotconf/security/writelist.xml | 21 + docs/docbook/smbdotconf/security/writeok.xml | 6 + docs/docbook/smbdotconf/smb.conf.5.xml | 685 +++++++++++++++++++++ docs/docbook/smbdotconf/smbconf.dtd | 7 + .../docbook/smbdotconf/split-original-smb.conf.xsl | 78 +++ docs/docbook/smbdotconf/tuning/blocksize.xml | 19 + .../smbdotconf/tuning/changenotifytimeout.xml | 15 + docs/docbook/smbdotconf/tuning/deadtime.xml | 23 + docs/docbook/smbdotconf/tuning/getwdcache.xml | 11 + docs/docbook/smbdotconf/tuning/hostnamelookups.xml | 14 + docs/docbook/smbdotconf/tuning/keepalive.xml | 16 + docs/docbook/smbdotconf/tuning/maxconnections.xml | 16 + docs/docbook/smbdotconf/tuning/maxdisksize.xml | 24 + docs/docbook/smbdotconf/tuning/maxopenfiles.xml | 16 + .../docbook/smbdotconf/tuning/maxsmbdprocesses.xml | 17 + docs/docbook/smbdotconf/tuning/minprintspace.xml | 14 + .../docbook/smbdotconf/tuning/namecachetimeout.xml | 12 + .../smbdotconf/tuning/paranoidserversecurity.xml | 16 + docs/docbook/smbdotconf/tuning/readsize.xml | 25 + docs/docbook/smbdotconf/tuning/socketoptions.xml | 69 +++ docs/docbook/smbdotconf/tuning/statcachesize.xml | 9 + docs/docbook/smbdotconf/tuning/strictallocate.xml | 21 + docs/docbook/smbdotconf/tuning/strictsync.xml | 23 + docs/docbook/smbdotconf/tuning/syncalways.xml | 19 + docs/docbook/smbdotconf/tuning/usemmap.xml | 14 + docs/docbook/smbdotconf/tuning/usesendfile.xml | 14 + docs/docbook/smbdotconf/tuning/writecachesize.xml | 27 + docs/docbook/smbdotconf/vfs/hostmsdfs.xml | 17 + docs/docbook/smbdotconf/vfs/msdfsproxy.xml | 15 + docs/docbook/smbdotconf/vfs/msdfsroot.xml | 19 + docs/docbook/smbdotconf/vfs/vfsobject.xml | 10 + docs/docbook/smbdotconf/vfs/vfsoptions.xml | 10 + docs/docbook/smbdotconf/vfs/vfspath.xml | 12 + .../docbook/smbdotconf/winbind/templatehomedir.xml | 13 + docs/docbook/smbdotconf/winbind/templateshell.xml | 10 + .../smbdotconf/winbind/winbindcachetime.xml | 11 + .../smbdotconf/winbind/winbindenumgroups.xml | 18 + .../smbdotconf/winbind/winbindenumusers.xml | 20 + docs/docbook/smbdotconf/winbind/winbindgid.xml | 14 + .../smbdotconf/winbind/winbindseparator.xml | 17 + docs/docbook/smbdotconf/winbind/winbinduid.xml | 14 + .../smbdotconf/winbind/winbindusedefaultdomain.xml | 14 + docs/docbook/smbdotconf/wins/dnsproxy.xml | 21 + docs/docbook/smbdotconf/wins/winshook.xml | 43 ++ docs/docbook/smbdotconf/wins/winspartners.xml | 14 + docs/docbook/smbdotconf/wins/winsproxy.xml | 9 + docs/docbook/smbdotconf/wins/winsserver.xml | 21 + docs/docbook/smbdotconf/wins/winssupport.xml | 12 + 323 files changed, 7843 insertions(+) create mode 100644 docs/docbook/smbdotconf/.cvsignore create mode 100644 docs/docbook/smbdotconf/README create mode 100644 docs/docbook/smbdotconf/base/adsserver.xml create mode 100644 docs/docbook/smbdotconf/base/bindinterfacesonly.xml create mode 100644 docs/docbook/smbdotconf/base/comment.xml create mode 100644 docs/docbook/smbdotconf/base/directory.xml create mode 100644 docs/docbook/smbdotconf/base/displaycharset.xml create mode 100644 docs/docbook/smbdotconf/base/doscharset.xml create mode 100644 docs/docbook/smbdotconf/base/interfaces.xml create mode 100644 docs/docbook/smbdotconf/base/netbiosaliases.xml create mode 100644 docs/docbook/smbdotconf/base/netbiosname.xml create mode 100644 docs/docbook/smbdotconf/base/netbiosscope.xml create mode 100644 docs/docbook/smbdotconf/base/path.xml create mode 100644 docs/docbook/smbdotconf/base/realm.xml create mode 100644 docs/docbook/smbdotconf/base/serverstring.xml create mode 100644 docs/docbook/smbdotconf/base/unixcharset.xml create mode 100644 docs/docbook/smbdotconf/base/workgroup.xml create mode 100644 docs/docbook/smbdotconf/browse/browsable.xml create mode 100644 docs/docbook/smbdotconf/browse/browseable.xml create mode 100644 docs/docbook/smbdotconf/browse/browselist.xml create mode 100644 docs/docbook/smbdotconf/browse/domainmaster.xml create mode 100644 docs/docbook/smbdotconf/browse/enhancedbrowsing.xml create mode 100644 docs/docbook/smbdotconf/browse/lmannounce.xml create mode 100644 docs/docbook/smbdotconf/browse/lminterval.xml create mode 100644 docs/docbook/smbdotconf/browse/localmaster.xml create mode 100644 docs/docbook/smbdotconf/browse/oslevel.xml create mode 100644 docs/docbook/smbdotconf/browse/preferedmaster.xml create mode 100644 docs/docbook/smbdotconf/browse/preferredmaster.xml create mode 100644 docs/docbook/smbdotconf/domain/machinepasswordtimeout.xml create mode 100644 docs/docbook/smbdotconf/expand-smb.conf.xsl create mode 100644 docs/docbook/smbdotconf/filename/casesensitive.xml create mode 100644 docs/docbook/smbdotconf/filename/casesignames.xml create mode 100644 docs/docbook/smbdotconf/filename/defaultcase.xml create mode 100644 docs/docbook/smbdotconf/filename/deletevetofiles.xml create mode 100644 docs/docbook/smbdotconf/filename/hidedotfiles.xml create mode 100644 docs/docbook/smbdotconf/filename/hidefiles.xml create mode 100644 docs/docbook/smbdotconf/filename/hidespecialfiles.xml create mode 100644 docs/docbook/smbdotconf/filename/hideunreadable.xml create mode 100644 docs/docbook/smbdotconf/filename/hideunwriteablefiles.xml create mode 100644 docs/docbook/smbdotconf/filename/manglecase.xml create mode 100644 docs/docbook/smbdotconf/filename/mangledmap.xml create mode 100644 docs/docbook/smbdotconf/filename/manglednames.xml create mode 100644 docs/docbook/smbdotconf/filename/mangledstack.xml create mode 100644 docs/docbook/smbdotconf/filename/mangleprefix.xml create mode 100644 docs/docbook/smbdotconf/filename/manglingchar.xml create mode 100644 docs/docbook/smbdotconf/filename/manglingmethod.xml create mode 100644 docs/docbook/smbdotconf/filename/maparchive.xml create mode 100644 docs/docbook/smbdotconf/filename/maphidden.xml create mode 100644 docs/docbook/smbdotconf/filename/mapsystem.xml create mode 100644 docs/docbook/smbdotconf/filename/preservecase.xml create mode 100644 docs/docbook/smbdotconf/filename/shortpreservecase.xml create mode 100644 docs/docbook/smbdotconf/filename/statcache.xml create mode 100644 docs/docbook/smbdotconf/filename/stripdot.xml create mode 100644 docs/docbook/smbdotconf/filename/vetofiles.xml create mode 100644 docs/docbook/smbdotconf/filename/vetooplockfiles.xml create mode 100644 docs/docbook/smbdotconf/generate-context.xsl create mode 100755 docs/docbook/smbdotconf/generate-file-list.sh create mode 100644 docs/docbook/smbdotconf/ldap/ldapadmindn.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapdeletedn.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapdelonlysamattr.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapfilter.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapmachinesuffix.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldappasswdsync.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapport.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapserver.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapssl.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapsuffix.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldaptrustids.xml create mode 100644 docs/docbook/smbdotconf/ldap/ldapusersuffix.xml create mode 100644 docs/docbook/smbdotconf/locking/blockinglocks.xml create mode 100644 docs/docbook/smbdotconf/locking/cscpolicy.xml create mode 100644 docs/docbook/smbdotconf/locking/fakeoplocks.xml create mode 100644 docs/docbook/smbdotconf/locking/kerneloplocks.xml create mode 100644 docs/docbook/smbdotconf/locking/level2oplocks.xml create mode 100644 docs/docbook/smbdotconf/locking/locking.xml create mode 100644 docs/docbook/smbdotconf/locking/lockspincount.xml create mode 100644 docs/docbook/smbdotconf/locking/lockspintime.xml create mode 100644 docs/docbook/smbdotconf/locking/oplockbreakwaittime.xml create mode 100644 docs/docbook/smbdotconf/locking/oplockcontentionlimit.xml create mode 100644 docs/docbook/smbdotconf/locking/oplocks.xml create mode 100644 docs/docbook/smbdotconf/locking/posixlocking.xml create mode 100644 docs/docbook/smbdotconf/locking/sharemodes.xml create mode 100644 docs/docbook/smbdotconf/locking/strictlocking.xml create mode 100644 docs/docbook/smbdotconf/logging/debughirestimestamp.xml create mode 100644 docs/docbook/smbdotconf/logging/debuglevel.xml create mode 100644 docs/docbook/smbdotconf/logging/debugpid.xml create mode 100644 docs/docbook/smbdotconf/logging/debugtimestamp.xml create mode 100644 docs/docbook/smbdotconf/logging/debuguid.xml create mode 100644 docs/docbook/smbdotconf/logging/logfile.xml create mode 100644 docs/docbook/smbdotconf/logging/loglevel.xml create mode 100644 docs/docbook/smbdotconf/logging/maxlogsize.xml create mode 100644 docs/docbook/smbdotconf/logging/syslog.xml create mode 100644 docs/docbook/smbdotconf/logging/syslogonly.xml create mode 100644 docs/docbook/smbdotconf/logging/timestamplogs.xml create mode 100644 docs/docbook/smbdotconf/logon/abortshutdownscript.xml create mode 100644 docs/docbook/smbdotconf/logon/addgroupscript.xml create mode 100644 docs/docbook/smbdotconf/logon/addmachinescript.xml create mode 100644 docs/docbook/smbdotconf/logon/adduserscript.xml create mode 100644 docs/docbook/smbdotconf/logon/addusertogroupscript.xml create mode 100644 docs/docbook/smbdotconf/logon/deletegroupscript.xml create mode 100644 docs/docbook/smbdotconf/logon/deleteuserfromgroupscript.xml create mode 100644 docs/docbook/smbdotconf/logon/deleteuserscript.xml create mode 100644 docs/docbook/smbdotconf/logon/domainlogons.xml create mode 100644 docs/docbook/smbdotconf/logon/logondrive.xml create mode 100644 docs/docbook/smbdotconf/logon/logonhome.xml create mode 100644 docs/docbook/smbdotconf/logon/logonpath.xml create mode 100644 docs/docbook/smbdotconf/logon/logonscript.xml create mode 100644 docs/docbook/smbdotconf/logon/shutdownscript.xml create mode 100644 docs/docbook/smbdotconf/man.xsl create mode 100644 docs/docbook/smbdotconf/misc/addsharecommand.xml create mode 100644 docs/docbook/smbdotconf/misc/autoservices.xml create mode 100644 docs/docbook/smbdotconf/misc/available.xml create mode 100644 docs/docbook/smbdotconf/misc/changesharecommand.xml create mode 100644 docs/docbook/smbdotconf/misc/configfile.xml create mode 100644 docs/docbook/smbdotconf/misc/copy.xml create mode 100644 docs/docbook/smbdotconf/misc/default.xml create mode 100644 docs/docbook/smbdotconf/misc/defaultservice.xml create mode 100644 docs/docbook/smbdotconf/misc/deletereadonly.xml create mode 100644 docs/docbook/smbdotconf/misc/deletesharecommand.xml create mode 100644 docs/docbook/smbdotconf/misc/dfreecommand.xml create mode 100644 docs/docbook/smbdotconf/misc/dontdescend.xml create mode 100644 docs/docbook/smbdotconf/misc/dosfilemode.xml create mode 100644 docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml create mode 100644 docs/docbook/smbdotconf/misc/dosfiletimes.xml create mode 100644 docs/docbook/smbdotconf/misc/exec.xml create mode 100644 docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml create mode 100644 docs/docbook/smbdotconf/misc/followsymlinks.xml create mode 100644 docs/docbook/smbdotconf/misc/fstype.xml create mode 100644 docs/docbook/smbdotconf/misc/hidelocalusers.xml create mode 100644 docs/docbook/smbdotconf/misc/homedirmap.xml create mode 100644 docs/docbook/smbdotconf/misc/include.xml create mode 100644 docs/docbook/smbdotconf/misc/lockdir.xml create mode 100644 docs/docbook/smbdotconf/misc/lockdirectory.xml create mode 100644 docs/docbook/smbdotconf/misc/magicoutput.xml create mode 100644 docs/docbook/smbdotconf/misc/magicscript.xml create mode 100644 docs/docbook/smbdotconf/misc/messagecommand.xml create mode 100644 docs/docbook/smbdotconf/misc/nishomedir.xml create mode 100644 docs/docbook/smbdotconf/misc/panicaction.xml create mode 100644 docs/docbook/smbdotconf/misc/piddirectory.xml create mode 100644 docs/docbook/smbdotconf/misc/postexec.xml create mode 100644 docs/docbook/smbdotconf/misc/preexec.xml create mode 100644 docs/docbook/smbdotconf/misc/preexecclose.xml create mode 100644 docs/docbook/smbdotconf/misc/preload.xml create mode 100644 docs/docbook/smbdotconf/misc/remoteannounce.xml create mode 100644 docs/docbook/smbdotconf/misc/remotebrowsesync.xml create mode 100644 docs/docbook/smbdotconf/misc/rootpostexec.xml create mode 100644 docs/docbook/smbdotconf/misc/rootpreexec.xml create mode 100644 docs/docbook/smbdotconf/misc/rootpreexecclose.xml create mode 100644 docs/docbook/smbdotconf/misc/setdirectory.xml create mode 100644 docs/docbook/smbdotconf/misc/socketaddress.xml create mode 100644 docs/docbook/smbdotconf/misc/sourceenvironment.xml create mode 100644 docs/docbook/smbdotconf/misc/timeoffset.xml create mode 100644 docs/docbook/smbdotconf/misc/utmp.xml create mode 100644 docs/docbook/smbdotconf/misc/utmpdirectory.xml create mode 100644 docs/docbook/smbdotconf/misc/volume.xml create mode 100644 docs/docbook/smbdotconf/misc/widelinks.xml create mode 100644 docs/docbook/smbdotconf/misc/wtmpdirectory.xml create mode 100644 docs/docbook/smbdotconf/printing/addprintercommand.xml create mode 100644 docs/docbook/smbdotconf/printing/defaultdevmode.xml create mode 100644 docs/docbook/smbdotconf/printing/deleteprintercommand.xml create mode 100644 docs/docbook/smbdotconf/printing/disablespoolss.xml create mode 100644 docs/docbook/smbdotconf/printing/enumportscommand.xml create mode 100644 docs/docbook/smbdotconf/printing/loadprinters.xml create mode 100644 docs/docbook/smbdotconf/printing/lppausecommand.xml create mode 100644 docs/docbook/smbdotconf/printing/lpqcachetime.xml create mode 100644 docs/docbook/smbdotconf/printing/lpqcommand.xml create mode 100644 docs/docbook/smbdotconf/printing/lpresumecommand.xml create mode 100644 docs/docbook/smbdotconf/printing/lprmcommand.xml create mode 100644 docs/docbook/smbdotconf/printing/maxprintjobs.xml create mode 100644 docs/docbook/smbdotconf/printing/os2drivermap.xml create mode 100644 docs/docbook/smbdotconf/printing/printable.xml create mode 100644 docs/docbook/smbdotconf/printing/printcap.xml create mode 100644 docs/docbook/smbdotconf/printing/printcapname.xml create mode 100644 docs/docbook/smbdotconf/printing/printcommand.xml create mode 100644 docs/docbook/smbdotconf/printing/printer.xml create mode 100644 docs/docbook/smbdotconf/printing/printername.xml create mode 100644 docs/docbook/smbdotconf/printing/printing.xml create mode 100644 docs/docbook/smbdotconf/printing/printok.xml create mode 100644 docs/docbook/smbdotconf/printing/queuepausecommand.xml create mode 100644 docs/docbook/smbdotconf/printing/queueresumecommand.xml create mode 100644 docs/docbook/smbdotconf/printing/showaddprinterwizard.xml create mode 100644 docs/docbook/smbdotconf/printing/totalprintjobs.xml create mode 100644 docs/docbook/smbdotconf/printing/useclientdriver.xml create mode 100755 docs/docbook/smbdotconf/process-all.sh create mode 100644 docs/docbook/smbdotconf/protocol/announceas.xml create mode 100644 docs/docbook/smbdotconf/protocol/announceversion.xml create mode 100644 docs/docbook/smbdotconf/protocol/disablenetbios.xml create mode 100644 docs/docbook/smbdotconf/protocol/largereadwrite.xml create mode 100644 docs/docbook/smbdotconf/protocol/maxmux.xml create mode 100644 docs/docbook/smbdotconf/protocol/maxprotocol.xml create mode 100644 docs/docbook/smbdotconf/protocol/maxttl.xml create mode 100644 docs/docbook/smbdotconf/protocol/maxwinsttl.xml create mode 100644 docs/docbook/smbdotconf/protocol/maxxmit.xml create mode 100644 docs/docbook/smbdotconf/protocol/minprotocol.xml create mode 100644 docs/docbook/smbdotconf/protocol/minwinsttl.xml create mode 100644 docs/docbook/smbdotconf/protocol/nameresolveorder.xml create mode 100644 docs/docbook/smbdotconf/protocol/ntaclsupport.xml create mode 100644 docs/docbook/smbdotconf/protocol/ntpipesupport.xml create mode 100644 docs/docbook/smbdotconf/protocol/ntstatussupport.xml create mode 100644 docs/docbook/smbdotconf/protocol/protocol.xml create mode 100644 docs/docbook/smbdotconf/protocol/readbmpx.xml create mode 100644 docs/docbook/smbdotconf/protocol/readraw.xml create mode 100644 docs/docbook/smbdotconf/protocol/smbports.xml create mode 100644 docs/docbook/smbdotconf/protocol/timeserver.xml create mode 100644 docs/docbook/smbdotconf/protocol/unicode.xml create mode 100644 docs/docbook/smbdotconf/protocol/unixextensions.xml create mode 100644 docs/docbook/smbdotconf/protocol/usespnego.xml create mode 100644 docs/docbook/smbdotconf/protocol/writeraw.xml create mode 100644 docs/docbook/smbdotconf/security/adminusers.xml create mode 100644 docs/docbook/smbdotconf/security/algorithmicridbase.xml create mode 100644 docs/docbook/smbdotconf/security/allowhosts.xml create mode 100644 docs/docbook/smbdotconf/security/allowtrusteddomains.xml create mode 100644 docs/docbook/smbdotconf/security/authmethods.xml create mode 100644 docs/docbook/smbdotconf/security/createmask.xml create mode 100644 docs/docbook/smbdotconf/security/createmode.xml create mode 100644 docs/docbook/smbdotconf/security/denyhosts.xml create mode 100644 docs/docbook/smbdotconf/security/directorymask.xml create mode 100644 docs/docbook/smbdotconf/security/directorymode.xml create mode 100644 docs/docbook/smbdotconf/security/directorysecuritymask.xml create mode 100644 docs/docbook/smbdotconf/security/encryptpasswords.xml create mode 100644 docs/docbook/smbdotconf/security/forcecreatemode.xml create mode 100644 docs/docbook/smbdotconf/security/forcedirectorymode.xml create mode 100644 docs/docbook/smbdotconf/security/forcedirectorysecuritymode.xml create mode 100644 docs/docbook/smbdotconf/security/forcegroup.xml create mode 100644 docs/docbook/smbdotconf/security/forcesecuritymode.xml create mode 100644 docs/docbook/smbdotconf/security/forceuser.xml create mode 100644 docs/docbook/smbdotconf/security/group.xml create mode 100644 docs/docbook/smbdotconf/security/guestaccount.xml create mode 100644 docs/docbook/smbdotconf/security/guestok.xml create mode 100644 docs/docbook/smbdotconf/security/guestonly.xml create mode 100644 docs/docbook/smbdotconf/security/hostsallow.xml create mode 100644 docs/docbook/smbdotconf/security/hostsdeny.xml create mode 100644 docs/docbook/smbdotconf/security/hostsequiv.xml create mode 100644 docs/docbook/smbdotconf/security/inheritacls.xml create mode 100644 docs/docbook/smbdotconf/security/inheritpermissions.xml create mode 100644 docs/docbook/smbdotconf/security/invalidusers.xml create mode 100644 docs/docbook/smbdotconf/security/lanmanauth.xml create mode 100644 docs/docbook/smbdotconf/security/maptoguest.xml create mode 100644 docs/docbook/smbdotconf/security/minpasswdlength.xml create mode 100644 docs/docbook/smbdotconf/security/minpasswordlength.xml create mode 100644 docs/docbook/smbdotconf/security/nonunixaccountrange.xml create mode 100644 docs/docbook/smbdotconf/security/ntlmauth.xml create mode 100644 docs/docbook/smbdotconf/security/nullpasswords.xml create mode 100644 docs/docbook/smbdotconf/security/obeypamrestrictions.xml create mode 100644 docs/docbook/smbdotconf/security/onlyguest.xml create mode 100644 docs/docbook/smbdotconf/security/onlyuser.xml create mode 100644 docs/docbook/smbdotconf/security/pampasswordchange.xml create mode 100644 docs/docbook/smbdotconf/security/passdbbackend.xml create mode 100644 docs/docbook/smbdotconf/security/passwdchat.xml create mode 100644 docs/docbook/smbdotconf/security/passwdchatdebug.xml create mode 100644 docs/docbook/smbdotconf/security/passwdprogram.xml create mode 100644 docs/docbook/smbdotconf/security/passwordlevel.xml create mode 100644 docs/docbook/smbdotconf/security/passwordserver.xml create mode 100644 docs/docbook/smbdotconf/security/printeradmin.xml create mode 100644 docs/docbook/smbdotconf/security/privatedir.xml create mode 100644 docs/docbook/smbdotconf/security/public.xml create mode 100644 docs/docbook/smbdotconf/security/readlist.xml create mode 100644 docs/docbook/smbdotconf/security/readonly.xml create mode 100644 docs/docbook/smbdotconf/security/restrictanonymous.xml create mode 100644 docs/docbook/smbdotconf/security/root.xml create mode 100644 docs/docbook/smbdotconf/security/rootdir.xml create mode 100644 docs/docbook/smbdotconf/security/rootdirectory.xml create mode 100644 docs/docbook/smbdotconf/security/security.xml create mode 100644 docs/docbook/smbdotconf/security/securitymask.xml create mode 100644 docs/docbook/smbdotconf/security/smbpasswdfile.xml create mode 100644 docs/docbook/smbdotconf/security/unixpasswordsync.xml create mode 100644 docs/docbook/smbdotconf/security/updateencrypted.xml create mode 100644 docs/docbook/smbdotconf/security/user.xml create mode 100644 docs/docbook/smbdotconf/security/username.xml create mode 100644 docs/docbook/smbdotconf/security/usernamelevel.xml create mode 100644 docs/docbook/smbdotconf/security/usernamemap.xml create mode 100644 docs/docbook/smbdotconf/security/users.xml create mode 100644 docs/docbook/smbdotconf/security/validusers.xml create mode 100644 docs/docbook/smbdotconf/security/writable.xml create mode 100644 docs/docbook/smbdotconf/security/writeable.xml create mode 100644 docs/docbook/smbdotconf/security/writelist.xml create mode 100644 docs/docbook/smbdotconf/security/writeok.xml create mode 100644 docs/docbook/smbdotconf/smb.conf.5.xml create mode 100644 docs/docbook/smbdotconf/smbconf.dtd create mode 100644 docs/docbook/smbdotconf/split-original-smb.conf.xsl create mode 100644 docs/docbook/smbdotconf/tuning/blocksize.xml create mode 100644 docs/docbook/smbdotconf/tuning/changenotifytimeout.xml create mode 100644 docs/docbook/smbdotconf/tuning/deadtime.xml create mode 100644 docs/docbook/smbdotconf/tuning/getwdcache.xml create mode 100644 docs/docbook/smbdotconf/tuning/hostnamelookups.xml create mode 100644 docs/docbook/smbdotconf/tuning/keepalive.xml create mode 100644 docs/docbook/smbdotconf/tuning/maxconnections.xml create mode 100644 docs/docbook/smbdotconf/tuning/maxdisksize.xml create mode 100644 docs/docbook/smbdotconf/tuning/maxopenfiles.xml create mode 100644 docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml create mode 100644 docs/docbook/smbdotconf/tuning/minprintspace.xml create mode 100644 docs/docbook/smbdotconf/tuning/namecachetimeout.xml create mode 100644 docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml create mode 100644 docs/docbook/smbdotconf/tuning/readsize.xml create mode 100644 docs/docbook/smbdotconf/tuning/socketoptions.xml create mode 100644 docs/docbook/smbdotconf/tuning/statcachesize.xml create mode 100644 docs/docbook/smbdotconf/tuning/strictallocate.xml create mode 100644 docs/docbook/smbdotconf/tuning/strictsync.xml create mode 100644 docs/docbook/smbdotconf/tuning/syncalways.xml create mode 100644 docs/docbook/smbdotconf/tuning/usemmap.xml create mode 100644 docs/docbook/smbdotconf/tuning/usesendfile.xml create mode 100644 docs/docbook/smbdotconf/tuning/writecachesize.xml create mode 100644 docs/docbook/smbdotconf/vfs/hostmsdfs.xml create mode 100644 docs/docbook/smbdotconf/vfs/msdfsproxy.xml create mode 100644 docs/docbook/smbdotconf/vfs/msdfsroot.xml create mode 100644 docs/docbook/smbdotconf/vfs/vfsobject.xml create mode 100644 docs/docbook/smbdotconf/vfs/vfsoptions.xml create mode 100644 docs/docbook/smbdotconf/vfs/vfspath.xml create mode 100644 docs/docbook/smbdotconf/winbind/templatehomedir.xml create mode 100644 docs/docbook/smbdotconf/winbind/templateshell.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindcachetime.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindenumgroups.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindenumusers.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindgid.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindseparator.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbinduid.xml create mode 100644 docs/docbook/smbdotconf/winbind/winbindusedefaultdomain.xml create mode 100644 docs/docbook/smbdotconf/wins/dnsproxy.xml create mode 100644 docs/docbook/smbdotconf/wins/winshook.xml create mode 100644 docs/docbook/smbdotconf/wins/winspartners.xml create mode 100644 docs/docbook/smbdotconf/wins/winsproxy.xml create mode 100644 docs/docbook/smbdotconf/wins/winsserver.xml create mode 100644 docs/docbook/smbdotconf/wins/winssupport.xml (limited to 'docs/docbook') diff --git a/docs/docbook/smbdotconf/.cvsignore b/docs/docbook/smbdotconf/.cvsignore new file mode 100644 index 0000000000..0f8c6cb0ed --- /dev/null +++ b/docs/docbook/smbdotconf/.cvsignore @@ -0,0 +1,4 @@ +parameters.all.xml +parameters.global.xml +parameters.service.xml + diff --git a/docs/docbook/smbdotconf/README b/docs/docbook/smbdotconf/README new file mode 100644 index 0000000000..f50a944e7b --- /dev/null +++ b/docs/docbook/smbdotconf/README @@ -0,0 +1,159 @@ +DocBook XML 4.2 source code for smb.conf(5) documentation for Samba 3.0 + +Author of the document: Alexander Bokovoy + +Welcome to new smb.conf(5) documentation build system! This directory +contains a new incarnation of Samba's smb.conf(5) Docbook XML 4.2 +sources. Note that the output might be unsatisfying untill all smb.conf(5) +parameters will converted to new format (see Chapter 4 for details). + +Content +------- + +0. Prerequisites +1. Structure +2. XSLT stylesheets +3. Usage +4. Current status of converted parameters + +Prerequisites +------------- + +In order to compile smb.conf(5) documentation from Docbook XML 4.2 +sources you'll need: + + - a working libxml2 and libxslt installation, together with xsltproc utility + + - a locally installed Docbook XSL 4.2 or higher + + - a working xmlcatalog to eliminate Web access for Docbook XSL + +The latter requisite is important: we do not specify local copies of +Docbook XSL stylesheets in our XSLTs because of real nightmare in their +location in most distributions. Fortunately, libxml2 provides standard +way to access locally installed external resources via so-called +'xmlcatalog' tool. It is working in RedHat, Mandrake, ALT Linux, and +some other distributions but wasn't at the moment of this writting (Late +March'03) in Debian. + +Structure +--------- + +smb.conf(5) sources consist of a number of XML files distributed across +a number of subdirectories. Each subdirectory represents a group of +smb.conf(5) parameters dedicated to one specific task as described in +Samba's loadparm.c source file (and shown in SWAT). + +Each XML file in subdirectories represents one parameter description, +together with some additional meta-information about it. Complete list +of meta-information attributes + +attribute description +------------------------------------------------------------------- +name smb.conf(5) parameter name +context G for global, S for services +basic set to 1 if loadparm.c's description +wizard includes appropriate flag for +advanced this parameter (FLAG_BASIC, +developer FLAG_ADVANCED, FLAG_WIZARD, FLAG_DEVELOPER) +------------------------------------------------------------------- + +Main XML file for smb.conf(5) is smb.conf.5.xml. It contains a general +stub for man page and several XML instructions to include: + + - a list of global parameters (auto-generated); + + - a list of service parameters (auto-generated); + + - a complete list of alphabetically sorted parameters (auto-generated). + +XSLT stylesheets +---------------- + +In order to combine and build final version of smb.conf(5) we apply a +set of XSLT stylesheets to smb.conf(5) sources. Following is the +complete description of existing stylesheets in smb.conf(5) source tree: + +1. [expand-smb.conf.xsl] Main driver, produces big XML source with all +smaller components combined. The resulted tree is then feed to Docbook +XSL for final producing. + +This stylesheet performs two main transformations: + + - Replaces tag by one; + + - Generates and tags for each . + +The latter step needs some explanation. We generate automatically + and tags based on meta-information about parameter. This +way all anchors have predictable names (capitalized parameter name with +all spaces supressed) and we really don't need to dublicate data. + +There was only one exception to the generation rule in smb.conf.5.sgml: +"use spnego" parameter had anchor SPNEGO which is now unified to +USESPNEGO. This also fixes a bug in SWAT which was unable to find SPNEGO +achnor. + +2. [generate-context.xsl] An utility stylesheet which main purpose is to +produce a list of parameters which are applicable for selected context +(global or service). + +The generate-context.xsl is run twice to generate both +parameters.global.xml and parameters.service.xml which are included then +by smb.conf.5.xml. This stylesheet relies on parameters.all.xml file +which is generated by [generate-file-list.sh] shell script. + +The parameters.all.xml file contains a complete list of include +instructions for XSLT processor to include all small XML files from +subdirectories. + +3. [man.xsl] Our local copy of Docbook XML to man(5) transformer. It +fixes some annoying errors in official Docbook XSL stylesheets and adds +our tuned parameters. This file really belongs to upper level where it +would occur later, as we'll move to Docbook XML completely. + +4. [split-original-smb.conf.xsl] This stylesheet isn't required anymore. +It was used for initial split of SGML-based smb.conf.5.sgml onto a set +of per-parameter XML files. I left it in source tree just for historical +interest. :) + +Usage +----- + +1. Generate [parameters.all.xml]: + sh generate-file-list.sh >parameters.all.xml + +2. Generate [parameters.global.xml]: + xsltproc --xinclude \ + --param smb.context "'G'" \ + --output parameters.global.xml \ + generate-context.xsl parameters.all.xml + +3. Generate [parameters.service.xml]: + xsltproc --xinclude \ + --param smb.context "'S'" \ + --output parameters.service.xml \ + generate-context.xsl parameters.all.xml + +4. Process smb.conf.5.xml (for example, to HTML): + xsltproc --xinclude expand-smb.conf.xsl smb.conf.5.xml | \ + xsltproc http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl - > smb.conf.5.html + +Note that in step 4 we are not saving preprocessed smb.conf.5.xml to +disk and directly passing it to the next XSLT processor (in this case -- +Docbook XML to HTML generator). + +For convenience, this sequence of commands is added into source tree as +process-all.sh + +Current state of converted parameters +------------------------------------- + +Only 'ads server' parameter converted so far to serve as example of +formatting. + +All undocumented parameters are listed in doc-status file in of Samba's +docs/ directory. + +Any help is greatly appreciated. + diff --git a/docs/docbook/smbdotconf/base/adsserver.xml b/docs/docbook/smbdotconf/base/adsserver.xml new file mode 100644 index 0000000000..4dd2a4b635 --- /dev/null +++ b/docs/docbook/smbdotconf/base/adsserver.xml @@ -0,0 +1,15 @@ + + + If this option is specified, samba does not try to figure out what + ads server to use itself, but uses the specified ads server. Either one + DNS name or IP address can be used. + + Default: ads server = + + Example: ads server = 192.168.1.2 + + + diff --git a/docs/docbook/smbdotconf/base/bindinterfacesonly.xml b/docs/docbook/smbdotconf/base/bindinterfacesonly.xml new file mode 100644 index 0000000000..78e1b02bf5 --- /dev/null +++ b/docs/docbook/smbdotconf/base/bindinterfacesonly.xml @@ -0,0 +1,66 @@ + + bind interfaces only (G) + This global parameter allows the Samba admin + to limit what interfaces on a machine will serve SMB requests. It + affects file service smbd + 8 and name service nmbd + 8 in a slightly different ways. + + For name service it causes nmbd to bind + to ports 137 and 138 on the interfaces listed in the interfaces parameter. nmbd + also binds to the "all addresses" interface (0.0.0.0) + on ports 137 and 138 for the purposes of reading broadcast messages. + If this option is not set then nmbd will service + name requests on all of these sockets. If bind interfaces + only is set then nmbd will check the + source address of any packets coming in on the broadcast sockets + and discard any that don't match the broadcast addresses of the + interfaces in the interfaces parameter list. + As unicast packets are received on the other sockets it allows + nmbd to refuse to serve names to machines that + send packets that arrive through any interfaces not listed in the + interfaces list. IP Source address spoofing + does defeat this simple check, however, so it must not be used + seriously as a security feature for nmbd. + + For file service it causes smbd + 8 to bind only to the interface list + given in the + interfaces parameter. This restricts the networks that + smbd will serve to packets coming in those + interfaces. Note that you should not use this parameter for machines + that are serving PPP or other intermittent or non-broadcast network + interfaces as it will not cope with non-permanent interfaces. + + If bind interfaces only is set then + unless the network address 127.0.0.1 is added + to the interfaces parameter list smbpasswd + 8 and swat + 8 may not work as expected due to the reasons covered below. + + To change a users SMB password, the smbpasswd + by default connects to the localhost - 127.0.0.1 + address as an SMB client to issue the password change request. If + bind interfaces only is set then unless the + network address 127.0.0.1 is added to the + interfaces parameter list then + smbpasswd will fail to connect in it's default mode. + smbpasswd can be forced to use the primary IP interface + of the local host by using its smbpasswd + 8 -r remote machine + parameter, with remote machine set + to the IP name of the primary interface of the local host. + + The swat status page tries to connect with + smbd and nmbd at the address + 127.0.0.1 to determine if they are running. + Not adding 127.0.0.1 will cause + smbd and nmbd to always show + "not running" even if they really are. This can prevent + swat from starting/stopping/restarting smbd + and nmbd. + + Default: bind interfaces only = no + + + diff --git a/docs/docbook/smbdotconf/base/comment.xml b/docs/docbook/smbdotconf/base/comment.xml new file mode 100644 index 0000000000..693268a0b0 --- /dev/null +++ b/docs/docbook/smbdotconf/base/comment.xml @@ -0,0 +1,14 @@ + + comment (S) + This is a text field that is seen next to a share + when a client does a queries the server, either via the network + neighborhood or via net view to list what shares + are available. + + If you want to set the string that is displayed next to the + machine name then see the + server string parameter. + + Default: No comment string + Example: comment = Fred's Files + diff --git a/docs/docbook/smbdotconf/base/directory.xml b/docs/docbook/smbdotconf/base/directory.xml new file mode 100644 index 0000000000..1ec4ab7e1a --- /dev/null +++ b/docs/docbook/smbdotconf/base/directory.xml @@ -0,0 +1,5 @@ + + directory (S) + Synonym for path + . + diff --git a/docs/docbook/smbdotconf/base/displaycharset.xml b/docs/docbook/smbdotconf/base/displaycharset.xml new file mode 100644 index 0000000000..add519e783 --- /dev/null +++ b/docs/docbook/smbdotconf/base/displaycharset.xml @@ -0,0 +1,13 @@ + + display charset (G) + Specifies the charset that samba will use + to print messages to stdout and stderr and SWAT will use. + Should generally be the same as the unix charset. + + + Default: display charset = ASCII + + Example: display charset = UTF8 + + + diff --git a/docs/docbook/smbdotconf/base/doscharset.xml b/docs/docbook/smbdotconf/base/doscharset.xml new file mode 100644 index 0000000000..db767e720c --- /dev/null +++ b/docs/docbook/smbdotconf/base/doscharset.xml @@ -0,0 +1,14 @@ + + dos charset (G) + DOS SMB clients assume the server has + the same charset as they do. This option specifies which + charset Samba should talk to DOS clients. + + + The default depends on which charsets you have installed. + Samba tries to use charset 850 but falls back to ASCII in + case it is not available. Run testparm + 1 to check the default on your system. + + + diff --git a/docs/docbook/smbdotconf/base/interfaces.xml b/docs/docbook/smbdotconf/base/interfaces.xml new file mode 100644 index 0000000000..1125ad0559 --- /dev/null +++ b/docs/docbook/smbdotconf/base/interfaces.xml @@ -0,0 +1,49 @@ + + interfaces (G) + This option allows you to override the default + network interfaces list that Samba will use for browsing, name + registration and other NBT traffic. By default Samba will query + the kernel for the list of all active interfaces and use any + interfaces except 127.0.0.1 that are broadcast capable. + + The option takes a list of interface strings. Each string + can be in any of the following forms: + + + a network interface name (such as eth0). + This may include shell-like wildcards so eth* will match + any interface starting with the substring "eth" + + an IP address. In this case the netmask is + determined from the list of interfaces obtained from the + kernel + + an IP/mask pair. + + a broadcast/mask pair. + + + The "mask" parameters can either be a bit length (such + as 24 for a C class network) or a full netmask in dotted + decimal form. + + The "IP" parameters above can either be a full dotted + decimal IP address or a hostname which will be looked up via + the OS's normal hostname resolution mechanisms. + + For example, the following line: + + interfaces = eth0 192.168.2.10/24 192.168.3.10/255.255.255.0 + + + would configure three network interfaces corresponding + to the eth0 device and IP addresses 192.168.2.10 and 192.168.3.10. + The netmasks of the latter two interfaces would be set to 255.255.255.0. + + See also bind + interfaces only. + + Default: all active interfaces except 127.0.0.1 + that are broadcast capable + + diff --git a/docs/docbook/smbdotconf/base/netbiosaliases.xml b/docs/docbook/smbdotconf/base/netbiosaliases.xml new file mode 100644 index 0000000000..b0a7688a83 --- /dev/null +++ b/docs/docbook/smbdotconf/base/netbiosaliases.xml @@ -0,0 +1,17 @@ + + netbios aliases (G) + This is a list of NetBIOS names that nmbd(8) will advertise as additional + names by which the Samba server is known. This allows one machine + to appear in browse lists under multiple names. If a machine is + acting as a browse server or logon server none + of these names will be advertised as either browse server or logon + servers, only the primary name of the machine will be advertised + with these capabilities. + + See also netbios + name. + + Default: empty string (no additional names) + Example: netbios aliases = TEST TEST1 TEST2 + + diff --git a/docs/docbook/smbdotconf/base/netbiosname.xml b/docs/docbook/smbdotconf/base/netbiosname.xml new file mode 100644 index 0000000000..2daf26e2b3 --- /dev/null +++ b/docs/docbook/smbdotconf/base/netbiosname.xml @@ -0,0 +1,16 @@ + + netbios name (G) + This sets the NetBIOS name by which a Samba + server is known. By default it is the same as the first component + of the host's DNS name. If a machine is a browse server or + logon server this name (or the first component + of the hosts DNS name) will be the name that these services are + advertised under. + + See also netbios + aliases. + + Default: machine DNS name + Example: netbios name = MYNAME + + diff --git a/docs/docbook/smbdotconf/base/netbiosscope.xml b/docs/docbook/smbdotconf/base/netbiosscope.xml new file mode 100644 index 0000000000..fd0e4ad40c --- /dev/null +++ b/docs/docbook/smbdotconf/base/netbiosscope.xml @@ -0,0 +1,7 @@ + + netbios scope (G) + This sets the NetBIOS scope that Samba will + operate under. This should not be set unless every machine + on your LAN also sets this value. + + diff --git a/docs/docbook/smbdotconf/base/path.xml b/docs/docbook/smbdotconf/base/path.xml new file mode 100644 index 0000000000..7d65e10b2b --- /dev/null +++ b/docs/docbook/smbdotconf/base/path.xml @@ -0,0 +1,27 @@ + + path (S) + This parameter specifies a directory to which + the user of the service is to be given access. In the case of + printable services, this is where print data will spool prior to + being submitted to the host for printing. + + For a printable service offering guest access, the service + should be readonly and the path should be world-writeable and + have the sticky bit set. This is not mandatory of course, but + you probably won't get the results you expect if you do + otherwise. + + Any occurrences of %u in the path + will be replaced with the UNIX username that the client is using + on this connection. Any occurrences of %m + will be replaced by the NetBIOS name of the machine they are + connecting from. These replacements are very useful for setting + up pseudo home directories for users. + + Note that this path will be based on + root dir if one was specified. + + Default: none + Example: path = /home/fred + + diff --git a/docs/docbook/smbdotconf/base/realm.xml b/docs/docbook/smbdotconf/base/realm.xml new file mode 100644 index 0000000000..50c7d26eea --- /dev/null +++ b/docs/docbook/smbdotconf/base/realm.xml @@ -0,0 +1,12 @@ + + realm (G) + + This option specifies the kerberos realm to use. The realm is + used as the ADS equivalent of the NT4domain. It + is usually set to the DNS name of the kerberos server. + + + Default: realm = + Example: realm = mysambabox.mycompany.com + + diff --git a/docs/docbook/smbdotconf/base/serverstring.xml b/docs/docbook/smbdotconf/base/serverstring.xml new file mode 100644 index 0000000000..a47ac4cf42 --- /dev/null +++ b/docs/docbook/smbdotconf/base/serverstring.xml @@ -0,0 +1,22 @@ + + server string (G) + This controls what string will show up in the + printer comment box in print manager and next to the IPC connection + in net view. It can be any string that you wish + to show to your users. + + It also sets what will appear in browse lists next + to the machine name. + + A %v will be replaced with the Samba + version number. + + A %h will be replaced with the + hostname. + + Default: server string = Samba %v + + Example: server string = University of GNUs Samba + Server + + diff --git a/docs/docbook/smbdotconf/base/unixcharset.xml b/docs/docbook/smbdotconf/base/unixcharset.xml new file mode 100644 index 0000000000..0ea84e38c8 --- /dev/null +++ b/docs/docbook/smbdotconf/base/unixcharset.xml @@ -0,0 +1,11 @@ + + unix charset (G) + Specifies the charset the unix machine + Samba runs on uses. Samba needs to know this in order to be able to + convert text to the charsets other SMB clients use. + + + Default: unix charset = UTF8 + Example: unix charset = ASCII + + diff --git a/docs/docbook/smbdotconf/base/workgroup.xml b/docs/docbook/smbdotconf/base/workgroup.xml new file mode 100644 index 0000000000..71ea89d202 --- /dev/null +++ b/docs/docbook/smbdotconf/base/workgroup.xml @@ -0,0 +1,11 @@ + + workgroup (G) + This controls what workgroup your server will + appear to be in when queried by clients. Note that this parameter + also controls the Domain name used with the security = domain + setting. + + Default: set at compile time to WORKGROUP + Example: workgroup = MYGROUP + + diff --git a/docs/docbook/smbdotconf/browse/browsable.xml b/docs/docbook/smbdotconf/browse/browsable.xml new file mode 100644 index 0000000000..779571cff2 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/browsable.xml @@ -0,0 +1,5 @@ + + browsable (S) + See the + browseable. + diff --git a/docs/docbook/smbdotconf/browse/browseable.xml b/docs/docbook/smbdotconf/browse/browseable.xml new file mode 100644 index 0000000000..c223d6c7d7 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/browseable.xml @@ -0,0 +1,8 @@ + + browseable (S) + This controls whether this share is seen in + the list of available shares in a net view and in the browse list. + + Default: browseable = yes + + diff --git a/docs/docbook/smbdotconf/browse/browselist.xml b/docs/docbook/smbdotconf/browse/browselist.xml new file mode 100644 index 0000000000..f15e2caf2a --- /dev/null +++ b/docs/docbook/smbdotconf/browse/browselist.xml @@ -0,0 +1,10 @@ + + browse list (G) + This controls whether smbd + 8 will serve a browse list to + a client doing a NetServerEnum call. Normally + set to yes. You should never need to change + this. + + Default: browse list = yes + diff --git a/docs/docbook/smbdotconf/browse/domainmaster.xml b/docs/docbook/smbdotconf/browse/domainmaster.xml new file mode 100644 index 0000000000..cf2d504e4d --- /dev/null +++ b/docs/docbook/smbdotconf/browse/domainmaster.xml @@ -0,0 +1,34 @@ + + domain master (G) + Tell smbd + 8 to enable WAN-wide browse list + collation. Setting this option causes nmbd to + claim a special domain specific NetBIOS name that identifies + it as a domain master browser for its given + workgroup. Local master browsers + in the same workgroup on broadcast-isolated + subnets will give this nmbd their local browse lists, + and then ask smbd + 8 for a complete copy of the browse + list for the whole wide area network. Browser clients will then contact + their local master browser, and will receive the domain-wide browse list, + instead of just the list for their broadcast-isolated subnet. + + Note that Windows NT Primary Domain Controllers expect to be + able to claim this workgroup specific special + NetBIOS name that identifies them as domain master browsers for + that workgroup by default (i.e. there is no + way to prevent a Windows NT PDC from attempting to do this). This + means that if this parameter is set and nmbd claims + the special name for a workgroup before a Windows + NT PDC is able to do so then cross subnet browsing will behave + strangely and may fail. + + If domain logons = yes + , then the default behavior is to enable the domain + master parameter. If domain logons is + not enabled (the default setting), then neither will domain + master be enabled by default. + + Default: domain master = auto + diff --git a/docs/docbook/smbdotconf/browse/enhancedbrowsing.xml b/docs/docbook/smbdotconf/browse/enhancedbrowsing.xml new file mode 100644 index 0000000000..cf8d3e54b9 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/enhancedbrowsing.xml @@ -0,0 +1,24 @@ + + enhanced browsing (G) + This option enables a couple of enhancements to + cross-subnet browse propagation that have been added in Samba + but which are not standard in Microsoft implementations. + + + The first enhancement to browse propagation consists of a regular + wildcard query to a Samba WINS server for all Domain Master Browsers, + followed by a browse synchronization with each of the returned + DMBs. The second enhancement consists of a regular randomised browse + synchronization with all currently known DMBs. + + You may wish to disable this option if you have a problem with empty + workgroups not disappearing from browse lists. Due to the restrictions + of the browse protocols these enhancements can cause a empty workgroup + to stay around forever which can be annoying. + + In general you should leave this option enabled as it makes + cross-subnet browse propagation much more reliable. + + Default: enhanced browsing = yes + + diff --git a/docs/docbook/smbdotconf/browse/lmannounce.xml b/docs/docbook/smbdotconf/browse/lmannounce.xml new file mode 100644 index 0000000000..1551c0991e --- /dev/null +++ b/docs/docbook/smbdotconf/browse/lmannounce.xml @@ -0,0 +1,24 @@ + + lm announce (G) + This parameter determines if nmbd + 8 will produce Lanman announce + broadcasts that are needed by OS/2 clients in order for them to see + the Samba server in their browse list. This parameter can have three + values, yes, no, or + auto. The default is auto. + If set to no Samba will never produce these + broadcasts. If set to yes Samba will produce + Lanman announce broadcasts at a frequency set by the parameter + lm interval. If set to auto + Samba will not send Lanman announce broadcasts by default but will + listen for them. If it hears such a broadcast on the wire it will + then start sending them at a frequency set by the parameter + lm interval. + + See also lm interval + . + + Default: lm announce = auto + Example: lm announce = yes + + diff --git a/docs/docbook/smbdotconf/browse/lminterval.xml b/docs/docbook/smbdotconf/browse/lminterval.xml new file mode 100644 index 0000000000..cc17dc15b0 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/lminterval.xml @@ -0,0 +1,17 @@ + + lm interval (G) + If Samba is set to produce Lanman announce + broadcasts needed by OS/2 clients (see the + lm announce parameter) then this + parameter defines the frequency in seconds with which they will be + made. If this is set to zero then no Lanman announcements will be + made despite the setting of the lm announce + parameter. + + See also lm + announce. + + Default: lm interval = 60 + Example: lm interval = 120 + + diff --git a/docs/docbook/smbdotconf/browse/localmaster.xml b/docs/docbook/smbdotconf/browse/localmaster.xml new file mode 100644 index 0000000000..dffbd3cb19 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/localmaster.xml @@ -0,0 +1,18 @@ + + local master (G) + This option allows nmbd + 8 to try and become a local master browser + on a subnet. If set to no then + nmbd will not attempt to become a local master browser + on a subnet and will also lose in all browsing elections. By + default this value is set to yes. Setting this value to yes doesn't + mean that Samba will become the local master + browser on a subnet, just that nmbd will + participate in elections for local master browser. + + Setting this value to no will cause nmbd + never to become a local master browser. + + Default: local master = yes + + diff --git a/docs/docbook/smbdotconf/browse/oslevel.xml b/docs/docbook/smbdotconf/browse/oslevel.xml new file mode 100644 index 0000000000..927db32204 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/oslevel.xml @@ -0,0 +1,21 @@ + + os level (G) + This integer value controls what level Samba + advertises itself as for browse elections. The value of this + parameter determines whether nmbd + 8 + has a chance of becoming a local master browser for the + WORKGROUP in the local broadcast area. + + Note :By default, Samba will win + a local master browsing election over all Microsoft operating + systems except a Windows NT 4.0/2000 Domain Controller. This + means that a misconfigured Samba host can effectively isolate + a subnet for browsing purposes. See BROWSING.txt + in the Samba docs/ directory + for details. + + Default: os level = 20 + Example: os level = 65 + + diff --git a/docs/docbook/smbdotconf/browse/preferedmaster.xml b/docs/docbook/smbdotconf/browse/preferedmaster.xml new file mode 100644 index 0000000000..8098626c51 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/preferedmaster.xml @@ -0,0 +1,6 @@ + + prefered master (G) + Synonym for + preferred master for people who cannot spell :-). + + diff --git a/docs/docbook/smbdotconf/browse/preferredmaster.xml b/docs/docbook/smbdotconf/browse/preferredmaster.xml new file mode 100644 index 0000000000..53934fdb78 --- /dev/null +++ b/docs/docbook/smbdotconf/browse/preferredmaster.xml @@ -0,0 +1,25 @@ + + preferred master (G) + This boolean parameter controls if nmbd(8) is a preferred master browser + for its workgroup. + + If this is set to yes, on startup, nmbd + will force an election, and it will have a slight advantage in + winning the election. It is recommended that this parameter is + used in conjunction with + domain master = yes, so that + nmbd can guarantee becoming a domain master. + + Use this option with caution, because if there are several + hosts (whether Samba servers, Windows 95 or NT) that are preferred + master browsers on the same subnet, they will each periodically + and continuously attempt to become the local master browser. + This will result in unnecessary broadcast traffic and reduced browsing + capabilities. + + See also os level + . + + Default: preferred master = auto + + diff --git a/docs/docbook/smbdotconf/domain/machinepasswordtimeout.xml b/docs/docbook/smbdotconf/domain/machinepasswordtimeout.xml new file mode 100644 index 0000000000..14e6d9c5df --- /dev/null +++ b/docs/docbook/smbdotconf/domain/machinepasswordtimeout.xml @@ -0,0 +1,18 @@ + + machine password timeout (G) + If a Samba server is a member of a Windows + NT Domain (see the security = domain) + parameter) then periodically a running + smbd(8) process will try and change the MACHINE ACCOUNT + PASSWORD stored in the TDB called private/secrets.tdb + . This parameter specifies how often this password + will be changed, in seconds. The default is one week (expressed in + seconds), the same as a Windows NT Domain member server. + + See also smbpasswd + 8, and the + security = domain) parameter. + + Default: machine password timeout = 604800 + + diff --git a/docs/docbook/smbdotconf/expand-smb.conf.xsl b/docs/docbook/smbdotconf/expand-smb.conf.xsl new file mode 100644 index 0000000000..87b4898cf7 --- /dev/null +++ b/docs/docbook/smbdotconf/expand-smb.conf.xsl @@ -0,0 +1,74 @@ + + + + + + + + + + + + + + + + + + + + + + Processing samba:parameter ( + + ) + + + + + + + + + + + + + + + ( + + ) + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docbook/smbdotconf/filename/casesensitive.xml b/docs/docbook/smbdotconf/filename/casesensitive.xml new file mode 100644 index 0000000000..622aea329e --- /dev/null +++ b/docs/docbook/smbdotconf/filename/casesensitive.xml @@ -0,0 +1,7 @@ + + case sensitive (S) + See the discussion in the section NAME MANGLING. + + Default: case sensitive = no + + diff --git a/docs/docbook/smbdotconf/filename/casesignames.xml b/docs/docbook/smbdotconf/filename/casesignames.xml new file mode 100644 index 0000000000..94bcb85984 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/casesignames.xml @@ -0,0 +1,5 @@ + + casesignames (S) + Synonym for case + sensitive. + diff --git a/docs/docbook/smbdotconf/filename/defaultcase.xml b/docs/docbook/smbdotconf/filename/defaultcase.xml new file mode 100644 index 0000000000..f2bdf5db1c --- /dev/null +++ b/docs/docbook/smbdotconf/filename/defaultcase.xml @@ -0,0 +1,9 @@ + + default case (S) + See the section on + NAME MANGLING. Also note the + short preserve case parameter. + + Default: default case = lower + + diff --git a/docs/docbook/smbdotconf/filename/deletevetofiles.xml b/docs/docbook/smbdotconf/filename/deletevetofiles.xml new file mode 100644 index 0000000000..49a5e2232f --- /dev/null +++ b/docs/docbook/smbdotconf/filename/deletevetofiles.xml @@ -0,0 +1,25 @@ + + delete veto files (S) + This option is used when Samba is attempting to + delete a directory that contains one or more vetoed directories + (see the veto files + option). If this option is set to no (the default) then if a vetoed + directory contains any non-vetoed files or directories then the + directory delete will fail. This is usually what you want. + + If this option is set to yes, then Samba + will attempt to recursively delete any files and directories within + the vetoed directory. This can be useful for integration with file + serving systems such as NetAtalk which create meta-files within + directories you might normally veto DOS/Windows users from seeing + (e.g. .AppleDouble) + + Setting delete veto files = yes allows these + directories to be transparently deleted when the parent directory + is deleted (so long as the user has permissions to do so). + + See also the veto + files parameter. + + Default: delete veto files = no + diff --git a/docs/docbook/smbdotconf/filename/hidedotfiles.xml b/docs/docbook/smbdotconf/filename/hidedotfiles.xml new file mode 100644 index 0000000000..63e87d8059 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/hidedotfiles.xml @@ -0,0 +1,7 @@ + + hide dot files (S) + This is a boolean parameter that controls whether + files starting with a dot appear as hidden files. + + Default: hide dot files = yes + diff --git a/docs/docbook/smbdotconf/filename/hidefiles.xml b/docs/docbook/smbdotconf/filename/hidefiles.xml new file mode 100644 index 0000000000..6f93a2a239 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/hidefiles.xml @@ -0,0 +1,35 @@ + + hide files(S) + This is a list of files or directories that are not + visible but are accessible. The DOS 'hidden' attribute is applied + to any files or directories that match. + + Each entry in the list must be separated by a '/', + which allows spaces to be included in the entry. '*' + and '?' can be used to specify multiple files or directories + as in DOS wildcards. + + Each entry must be a Unix path, not a DOS path and must + not include the Unix directory separator '/'. + + Note that the case sensitivity option is applicable + in hiding files. + + Setting this parameter will affect the performance of Samba, + as it will be forced to check all files and directories for a match + as they are scanned. + + See also hide + dot files, + veto files and + case sensitive. + + Default: no file are hidden + Example: hide files = + /.*/DesktopFolderDB/TrashFor%m/resource.frk/ + + The above example is based on files that the Macintosh + SMB client (DAVE) available from + Thursby creates for internal use, and also still hides + all files beginning with a dot. + diff --git a/docs/docbook/smbdotconf/filename/hidespecialfiles.xml b/docs/docbook/smbdotconf/filename/hidespecialfiles.xml new file mode 100644 index 0000000000..9a8c206097 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/hidespecialfiles.xml @@ -0,0 +1,10 @@ + + hide special files (G) + This parameter prevents clients from seeing + special files such as sockets, devices and fifo's in directory + listings. + + + Default: hide special files = no + + diff --git a/docs/docbook/smbdotconf/filename/hideunreadable.xml b/docs/docbook/smbdotconf/filename/hideunreadable.xml new file mode 100644 index 0000000000..d25153f103 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/hideunreadable.xml @@ -0,0 +1,8 @@ + + hide unreadable (G) + This parameter prevents clients from seeing the + existance of files that cannot be read. Defaults to off. + + Default: hide unreadable = no + + diff --git a/docs/docbook/smbdotconf/filename/hideunwriteablefiles.xml b/docs/docbook/smbdotconf/filename/hideunwriteablefiles.xml new file mode 100644 index 0000000000..9e28e8de5c --- /dev/null +++ b/docs/docbook/smbdotconf/filename/hideunwriteablefiles.xml @@ -0,0 +1,10 @@ + + hide unwriteable files (G) + This parameter prevents clients from seeing + the existance of files that cannot be written to. Defaults to off. + Note that unwriteable directories are shown as usual. + + + Default: hide unwriteable = no + + diff --git a/docs/docbook/smbdotconf/filename/manglecase.xml b/docs/docbook/smbdotconf/filename/manglecase.xml new file mode 100644 index 0000000000..170d77d453 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/manglecase.xml @@ -0,0 +1,8 @@ + + mangle case (S) + See the section on + NAME MANGLING + + Default: mangle case = no + + diff --git a/docs/docbook/smbdotconf/filename/mangledmap.xml b/docs/docbook/smbdotconf/filename/mangledmap.xml new file mode 100644 index 0000000000..abe6c031e0 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/mangledmap.xml @@ -0,0 +1,23 @@ + + mangled map (S) + This is for those who want to directly map UNIX + file names which cannot be represented on Windows/DOS. The mangling + of names is not always what is needed. In particular you may have + documents with file extensions that differ between DOS and UNIX. + For example, under UNIX it is common to use .html + for HTML files, whereas under Windows/DOS .htm + is more commonly used. + + So to map html to htm + you would use: + + mangled map = (*.html *.htm) + + One very useful case is to remove the annoying ;1 + off the ends of filenames on some CDROMs (only visible + under some UNIXes). To do this use a map of (*;1 *;). + + Default: no mangled map + Example: mangled map = (*;1 *;) + + diff --git a/docs/docbook/smbdotconf/filename/manglednames.xml b/docs/docbook/smbdotconf/filename/manglednames.xml new file mode 100644 index 0000000000..41592b3159 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/manglednames.xml @@ -0,0 +1,58 @@ + + mangled names (S) + This controls whether non-DOS names under UNIX + should be mapped to DOS-compatible names ("mangled") and made visible, + or whether non-DOS names should simply be ignored. + + See the section on + NAME MANGLING for details on how to control the mangling process. + + If mangling is used then the mangling algorithm is as follows: + + + The first (up to) five alphanumeric characters + before the rightmost dot of the filename are preserved, forced + to upper case, and appear as the first (up to) five characters + of the mangled name. + + A tilde "~" is appended to the first part of the mangled + name, followed by a two-character unique sequence, based on the + original root name (i.e., the original filename minus its final + extension). The final extension is included in the hash calculation + only if it contains any upper case characters or is longer than three + characters. + + Note that the character to use may be specified using + the mangling char + option, if you don't like '~'. + + The first three alphanumeric characters of the final + extension are preserved, forced to upper case and appear as the + extension of the mangled name. The final extension is defined as that + part of the original filename after the rightmost dot. If there are no + dots in the filename, the mangled name will have no extension (except + in the case of "hidden files" - see below). + + Files whose UNIX name begins with a dot will be + presented as DOS hidden files. The mangled name will be created as + for other filenames, but with the leading dot removed and "___" as + its extension regardless of actual original extension (that's three + underscores). + + + The two-digit hash value consists of upper case + alphanumeric characters. + + This algorithm can cause name collisions only if files + in a directory share the same first five alphanumeric characters. + The probability of such a clash is 1/1300. + + The name mangling (if enabled) allows a file to be + copied between UNIX directories from Windows/DOS while retaining + the long UNIX filename. UNIX files can be renamed to a new extension + from Windows/DOS and will retain the same basename. Mangled names + do not change between sessions. + + Default: mangled names = yes + + diff --git a/docs/docbook/smbdotconf/filename/mangledstack.xml b/docs/docbook/smbdotconf/filename/mangledstack.xml new file mode 100644 index 0000000000..3e6099ba92 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/mangledstack.xml @@ -0,0 +1,23 @@ + + mangled stack (G) + This parameter controls the number of mangled names + that should be cached in the Samba server smbd + 8. + + This stack is a list of recently mangled base names + (extensions are only maintained if they are longer than 3 characters + or contains upper case characters). + + The larger this value, the more likely it is that mangled + names can be successfully converted to correct long UNIX names. + However, large stack sizes will slow most directory accesses. Smaller + stacks save memory in the server (each stack element costs 256 bytes). + + + It is not possible to absolutely guarantee correct long + filenames, so be prepared for some surprises! + + Default: mangled stack = 50 + Example: mangled stack = 100 + + diff --git a/docs/docbook/smbdotconf/filename/mangleprefix.xml b/docs/docbook/smbdotconf/filename/mangleprefix.xml new file mode 100644 index 0000000000..7dfd46199c --- /dev/null +++ b/docs/docbook/smbdotconf/filename/mangleprefix.xml @@ -0,0 +1,11 @@ + + mangle prefix (G) + controls the number of prefix + characters from the original name used when generating + the mangled names. A larger value will give a weaker + hash and therefore more name collisions. The minimum + value is 1 and the maximum value is 6. + Default: mangle prefix = 1 + Example: mangle prefix = 4 + + diff --git a/docs/docbook/smbdotconf/filename/manglingchar.xml b/docs/docbook/smbdotconf/filename/manglingchar.xml new file mode 100644 index 0000000000..e6a9050466 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/manglingchar.xml @@ -0,0 +1,11 @@ + + mangling char (S) + This controls what character is used as + the magic character in name mangling. The default is a '~' + but this may interfere with some software. Use this option to set + it to whatever you prefer. + + Default: mangling char = ~ + Example: mangling char = ^ + + diff --git a/docs/docbook/smbdotconf/filename/manglingmethod.xml b/docs/docbook/smbdotconf/filename/manglingmethod.xml new file mode 100644 index 0000000000..11f9e9eb01 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/manglingmethod.xml @@ -0,0 +1,14 @@ + + mangling method (G) + controls the algorithm used for the generating + the mangled names. Can take two different values, "hash" and + "hash2". "hash" is the default and is the algorithm that has been + used in Samba for many years. "hash2" is a newer and considered + a better algorithm (generates less collisions) in the names. + However, many Win32 applications store the mangled names and so + changing to the new algorithm must not be done + lightly as these applications may break unless reinstalled. + Default: mangling method = hash2 + Example: mangling method = hash + + diff --git a/docs/docbook/smbdotconf/filename/maparchive.xml b/docs/docbook/smbdotconf/filename/maparchive.xml new file mode 100644 index 0000000000..18f39791aa --- /dev/null +++ b/docs/docbook/smbdotconf/filename/maparchive.xml @@ -0,0 +1,17 @@ + + map archive (S) + This controls whether the DOS archive attribute + should be mapped to the UNIX owner execute bit. The DOS archive bit + is set when a file has been modified since its last backup. One + motivation for this option it to keep Samba/your PC from making + any file it touches from becoming executable under UNIX. This can + be quite annoying for shared source code, documents, etc... + + Note that this requires the create mask + parameter to be set such that owner execute bit is not masked out + (i.e. it must include 100). See the parameter + create mask for details. + + Default: map archive = yes + + diff --git a/docs/docbook/smbdotconf/filename/maphidden.xml b/docs/docbook/smbdotconf/filename/maphidden.xml new file mode 100644 index 0000000000..2b0266c23e --- /dev/null +++ b/docs/docbook/smbdotconf/filename/maphidden.xml @@ -0,0 +1,13 @@ + + map hidden (S) + This controls whether DOS style hidden files + should be mapped to the UNIX world execute bit. + + Note that this requires the create mask + to be set such that the world execute bit is not masked out (i.e. + it must include 001). See the parameter + create mask for details. + + Default: map hidden = no + + diff --git a/docs/docbook/smbdotconf/filename/mapsystem.xml b/docs/docbook/smbdotconf/filename/mapsystem.xml new file mode 100644 index 0000000000..ead629971a --- /dev/null +++ b/docs/docbook/smbdotconf/filename/mapsystem.xml @@ -0,0 +1,13 @@ + + map system (S) + This controls whether DOS style system files + should be mapped to the UNIX group execute bit. + + Note that this requires the create mask + to be set such that the group execute bit is not masked out (i.e. + it must include 010). See the parameter + create mask for details. + + Default: map system = no + + diff --git a/docs/docbook/smbdotconf/filename/preservecase.xml b/docs/docbook/smbdotconf/filename/preservecase.xml new file mode 100644 index 0000000000..3be458ce15 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/preservecase.xml @@ -0,0 +1,13 @@ + + preserve case (S) + This controls if new filenames are created + with the case that the client passes, or if they are forced to + be the default case + . + + Default: preserve case = yes + + See the section on NAME + MANGLING for a fuller discussion. + + diff --git a/docs/docbook/smbdotconf/filename/shortpreservecase.xml b/docs/docbook/smbdotconf/filename/shortpreservecase.xml new file mode 100644 index 0000000000..1c8b36380d --- /dev/null +++ b/docs/docbook/smbdotconf/filename/shortpreservecase.xml @@ -0,0 +1,16 @@ + + short preserve case (S) + This boolean parameter controls if new files + which conform to 8.3 syntax, that is all in upper case and of + suitable length, are created upper case, or if they are forced + to be the default case + . This option can be use with preserve case = yes + to permit long filenames to retain their case, while short + names are lowered. + + See the section on + NAME MANGLING. + + Default: short preserve case = yes + + diff --git a/docs/docbook/smbdotconf/filename/statcache.xml b/docs/docbook/smbdotconf/filename/statcache.xml new file mode 100644 index 0000000000..ee94081483 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/statcache.xml @@ -0,0 +1,10 @@ + + stat cache (G) + This parameter determines if smbd + 8 will use a cache in order to + speed up case insensitive name mappings. You should never need + to change this parameter. + + Default: stat cache = yes + + diff --git a/docs/docbook/smbdotconf/filename/stripdot.xml b/docs/docbook/smbdotconf/filename/stripdot.xml new file mode 100644 index 0000000000..ff877144a6 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/stripdot.xml @@ -0,0 +1,9 @@ + + strip dot (G) + This is a boolean that controls whether to + strip trailing dots off UNIX filenames. This helps with some + CDROMs that have filenames ending in a single dot. + + Default: strip dot = no + + diff --git a/docs/docbook/smbdotconf/filename/vetofiles.xml b/docs/docbook/smbdotconf/filename/vetofiles.xml new file mode 100644 index 0000000000..faef2040b9 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/vetofiles.xml @@ -0,0 +1,46 @@ + + veto files(S) + This is a list of files and directories that + are neither visible nor accessible. Each entry in the list must + be separated by a '/', which allows spaces to be included + in the entry. '*' and '?' can be used to specify multiple files + or directories as in DOS wildcards. + + Each entry must be a unix path, not a DOS path and + must not include the unix directory + separator '/'. + + Note that the case sensitive option + is applicable in vetoing files. + + One feature of the veto files parameter that it + is important to be aware of is Samba's behaviour when + trying to delete a directory. If a directory that is + to be deleted contains nothing but veto files this + deletion will fail unless you also set + the delete veto files parameter to + yes. + + Setting this parameter will affect the performance + of Samba, as it will be forced to check all files and directories + for a match as they are scanned. + + See also hide files + and + case sensitive. + + Default: No files or directories are vetoed. + + +Examples: +; Veto any files containing the word Security, +; any ending in .tmp, and any directory containing the +; word root. +veto files = /*Security*/*.tmp/*root*/ + +; Veto the Apple specific files that a NetAtalk server +; creates. +veto files = /.AppleDouble/.bin/.AppleDesktop/Network Trash Folder/ + + + diff --git a/docs/docbook/smbdotconf/filename/vetooplockfiles.xml b/docs/docbook/smbdotconf/filename/vetooplockfiles.xml new file mode 100644 index 0000000000..0c817c97f8 --- /dev/null +++ b/docs/docbook/smbdotconf/filename/vetooplockfiles.xml @@ -0,0 +1,24 @@ + + veto oplock files (S) + This parameter is only valid when the oplocks + parameter is turned on for a share. It allows the Samba administrator + to selectively turn off the granting of oplocks on selected files that + match a wildcarded list, similar to the wildcarded list used in the + veto files + parameter. + + Default: No files are vetoed for oplock + grants + + You might want to do this on files that you know will + be heavily contended for by clients. A good example of this + is in the NetBench SMB benchmark program, which causes heavy + client contention for files ending in .SEM. + To cause Samba not to grant oplocks on these files you would use + the line (either in the [global] section or in the section for + the particular NetBench share : + + Example: veto oplock files = /*.SEM/ + + + diff --git a/docs/docbook/smbdotconf/generate-context.xsl b/docs/docbook/smbdotconf/generate-context.xsl new file mode 100644 index 0000000000..c9ca31085c --- /dev/null +++ b/docs/docbook/smbdotconf/generate-context.xsl @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + + + + + + + + Processing samba:parameter ( + + ) + + + + + + + + + + + + + + none + + + + + + + + + + + diff --git a/docs/docbook/smbdotconf/generate-file-list.sh b/docs/docbook/smbdotconf/generate-file-list.sh new file mode 100755 index 0000000000..f61ac4f49c --- /dev/null +++ b/docs/docbook/smbdotconf/generate-file-list.sh @@ -0,0 +1,8 @@ +#!/bin/sh +echo "" +find . -type f -name '*.xml' -mindepth 2 | sort | + while read ; do + echo "" + done + +echo "" diff --git a/docs/docbook/smbdotconf/ldap/ldapadmindn.xml b/docs/docbook/smbdotconf/ldap/ldapadmindn.xml new file mode 100644 index 0000000000..f92e8ce310 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapadmindn.xml @@ -0,0 +1,13 @@ + + ldap admin dn (G) + The ldap admin dn defines the Distinguished + Name (DN) name used by Samba to contact the ldap server when retreiving + user account information. The ldap + admin dn is used in conjunction with the admin dn password + stored in the private/secrets.tdb file. See the + smbpasswd + 8 man page for more information on how + to accmplish this. + + + diff --git a/docs/docbook/smbdotconf/ldap/ldapdeletedn.xml b/docs/docbook/smbdotconf/ldap/ldapdeletedn.xml new file mode 100644 index 0000000000..2b081853c6 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapdeletedn.xml @@ -0,0 +1,10 @@ + + ldap del only sam attr (G) + This parameter specifies whether a delete + operation in the ldapsam deletes the complete entry or only the attributes + specific to Samba. + + + Default : ldap delete dn = no + + diff --git a/docs/docbook/smbdotconf/ldap/ldapdelonlysamattr.xml b/docs/docbook/smbdotconf/ldap/ldapdelonlysamattr.xml new file mode 100644 index 0000000000..bae5b51e60 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapdelonlysamattr.xml @@ -0,0 +1,6 @@ + + ldap del only sam attr (G) + Inverted synonym for + ldap delete dn. + + diff --git a/docs/docbook/smbdotconf/ldap/ldapfilter.xml b/docs/docbook/smbdotconf/ldap/ldapfilter.xml new file mode 100644 index 0000000000..6ddf8db30f --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapfilter.xml @@ -0,0 +1,12 @@ + + ldap filter (G) + This parameter specifies the RFC 2254 compliant LDAP search filter. + The default is to match the login name with the uid + attribute for all entries matching the sambaAccount + objectclass. Note that this filter should only return one entry. + + + + Default : ldap filter = (&(uid=%u)(objectclass=sambaAccount)) + + diff --git a/docs/docbook/smbdotconf/ldap/ldapmachinesuffix.xml b/docs/docbook/smbdotconf/ldap/ldapmachinesuffix.xml new file mode 100644 index 0000000000..e02bf9acfc --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapmachinesuffix.xml @@ -0,0 +1,11 @@ + + ldap machine suffix (G) + It specifies where machines should be + added to the ldap tree. + + + + + Default : none + + diff --git a/docs/docbook/smbdotconf/ldap/ldappasswdsync.xml b/docs/docbook/smbdotconf/ldap/ldappasswdsync.xml new file mode 100644 index 0000000000..ce9449374d --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldappasswdsync.xml @@ -0,0 +1,23 @@ + + ldap passwd sync (G) + This option is used to define whether + or not Samba should sync the LDAP password with the NT + and LM hashes for normal accounts (NOT for + workstation, server or domain trusts) on a password + change via SAMBA. + + + + The ldap passwd sync can be set to one of three values: + + + Yes = Try to update the LDAP, NT and LM passwords and update the pwdLastSet time. + + No = Update NT and LM passwords and update the pwdLastSet time. + + Only = Only update the LDAP password and let the LDAP server do the rest. + + + Default : ldap passwd sync = no + + diff --git a/docs/docbook/smbdotconf/ldap/ldapport.xml b/docs/docbook/smbdotconf/ldap/ldapport.xml new file mode 100644 index 0000000000..97c256d423 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapport.xml @@ -0,0 +1,20 @@ + + ldap port (G) + This parameter is only available if Samba has been + configure to include the --with-ldapsam option + at compile time. + + + + This option is used to control the tcp port number used to contact + the ldap server. + The default is to use the stand LDAPS port 636. + + + See Also: ldap ssl + + + Default : ldap port = 636 ; if ldap ssl = on + Default : ldap port = 389 ; if ldap ssl = off + + diff --git a/docs/docbook/smbdotconf/ldap/ldapserver.xml b/docs/docbook/smbdotconf/ldap/ldapserver.xml new file mode 100644 index 0000000000..33d5652ac9 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapserver.xml @@ -0,0 +1,15 @@ + + ldap server (G) + This parameter is only available if Samba has been + configure to include the --with-ldapsam option + at compile time. + + + + This parameter should contain the FQDN of the ldap directory + server which should be queried to locate user account information. + + + Default : ldap server = localhost + + diff --git a/docs/docbook/smbdotconf/ldap/ldapssl.xml b/docs/docbook/smbdotconf/ldap/ldapssl.xml new file mode 100644 index 0000000000..d747d8f7df --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapssl.xml @@ -0,0 +1,30 @@ + + ldap ssl (G) + This option is used to define whether or not Samba should + use SSL when connecting to the ldap server + This is NOT related to + Samba's previous SSL support which was enabled by specifying the + --with-ssl option to the configure + script. + + + + The ldap ssl can be set to one of three values: + + + Off = Never use SSL when querying the directory. + + Start_tls = Use the LDAPv3 StartTLS extended operation + (RFC2830) for communicating with the directory server. + + On = + Use SSL on the ldaps port when contacting the + ldap server. Only + available when the backwards-compatiblity + --with-ldapsam option is specified + to configure. See passdb backend + + + Default : ldap ssl = start_tls + + diff --git a/docs/docbook/smbdotconf/ldap/ldapsuffix.xml b/docs/docbook/smbdotconf/ldap/ldapsuffix.xml new file mode 100644 index 0000000000..dae15f8104 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapsuffix.xml @@ -0,0 +1,8 @@ + + ldap suffix (G) + + Specifies where user and machine accounts are added to the tree. Can be overriden by ldap user suffix and ldap machine suffix. It also used as the base dn for all ldap searches. + + Default : none + + diff --git a/docs/docbook/smbdotconf/ldap/ldaptrustids.xml b/docs/docbook/smbdotconf/ldap/ldaptrustids.xml new file mode 100644 index 0000000000..8fe4a1400b --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldaptrustids.xml @@ -0,0 +1,18 @@ + + ldap trust ids (G) + Normally, Samba validates each entry + in the LDAP server against getpwnam(). This allows + LDAP to be used for Samba with the unix system using + NIS (for example) and also ensures that Samba does not + present accounts that do not otherwise exist. + This option is used to disable this functionality, and + instead to rely on the presence of the appropriate + attributes in LDAP directly, which can result in a + significant performance boost in some situations. + Setting this option to yes effectivly assumes + that the local machine is running nss_ldap against the + same LDAP server. + + Default: ldap trust ids = No + + diff --git a/docs/docbook/smbdotconf/ldap/ldapusersuffix.xml b/docs/docbook/smbdotconf/ldap/ldapusersuffix.xml new file mode 100644 index 0000000000..e4fb681e23 --- /dev/null +++ b/docs/docbook/smbdotconf/ldap/ldapusersuffix.xml @@ -0,0 +1,10 @@ + + ldap user suffix (G) + It specifies where users are added to the tree. + + + + + Default : none + + diff --git a/docs/docbook/smbdotconf/locking/blockinglocks.xml b/docs/docbook/smbdotconf/locking/blockinglocks.xml new file mode 100644 index 0000000000..ea5e90b5cd --- /dev/null +++ b/docs/docbook/smbdotconf/locking/blockinglocks.xml @@ -0,0 +1,22 @@ + + blocking locks (S) + This parameter controls the behavior + of smbd + 8 when given a request by a client + to obtain a byte range lock on a region of an open file, and the + request has a time limit associated with it. + + If this parameter is set and the lock range requested + cannot be immediately satisfied, samba will internally + queue the lock request, and periodically attempt to obtain + the lock until the timeout period expires. + + If this parameter is set to no, then + samba will behave as previous versions of Samba would and + will fail the lock request immediately if the lock range + cannot be obtained. + + Default: blocking locks = yes + + + diff --git a/docs/docbook/smbdotconf/locking/cscpolicy.xml b/docs/docbook/smbdotconf/locking/cscpolicy.xml new file mode 100644 index 0000000000..e5139bc4f3 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/cscpolicy.xml @@ -0,0 +1,18 @@ + + csc policy (S) + This stands for client-side caching + policy, and specifies how clients capable of offline + caching will cache the files in the share. The valid values + are: manual, documents, programs, disable. + + These values correspond to those used on Windows + servers. + + For example, shares containing roaming profiles can have + offline caching disabled using csc policy = disable + . + + Default: csc policy = manual + Example: csc policy = programs + + diff --git a/docs/docbook/smbdotconf/locking/fakeoplocks.xml b/docs/docbook/smbdotconf/locking/fakeoplocks.xml new file mode 100644 index 0000000000..16887726c0 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/fakeoplocks.xml @@ -0,0 +1,27 @@ + + fake oplocks (S) + Oplocks are the way that SMB clients get permission + from a server to locally cache file operations. If a server grants + an oplock (opportunistic lock) then the client is free to assume + that it is the only one accessing the file and it will aggressively + cache file data. With some oplock types the client may even cache + file open/close operations. This can give enormous performance benefits. + + + When you set fake oplocks = yes, smbd(8) will + always grant oplock requests no matter how many clients are using + the file. + + It is generally much better to use the real oplocks support rather + than this parameter. + + If you enable this option on all read-only shares or + shares that you know will only be accessed from one client at a + time such as physically read-only media like CDROMs, you will see + a big performance improvement on many operations. If you enable + this option on shares where multiple clients may be accessing the + files read-write at the same time you can get data corruption. Use + this option carefully! + + Default: fake oplocks = no + diff --git a/docs/docbook/smbdotconf/locking/kerneloplocks.xml b/docs/docbook/smbdotconf/locking/kerneloplocks.xml new file mode 100644 index 0000000000..98513fdd1e --- /dev/null +++ b/docs/docbook/smbdotconf/locking/kerneloplocks.xml @@ -0,0 +1,24 @@ + + kernel oplocks (G) + For UNIXes that support kernel based oplocks + (currently only IRIX and the Linux 2.4 kernel), this parameter + allows the use of them to be turned on or off. + + Kernel oplocks support allows Samba oplocks + to be broken whenever a local UNIX process or NFS operation + accesses a file that smbd + 8 has oplocked. This allows complete + data consistency between SMB/CIFS, NFS and local file access (and is + a very cool feature :-). + + This parameter defaults to on, but is translated + to a no-op on systems that no not have the necessary kernel support. + You should never need to touch this parameter. + + See also the oplocks + and level2 oplocks + parameters. + + Default: kernel oplocks = yes + + diff --git a/docs/docbook/smbdotconf/locking/level2oplocks.xml b/docs/docbook/smbdotconf/locking/level2oplocks.xml new file mode 100644 index 0000000000..adae6d268f --- /dev/null +++ b/docs/docbook/smbdotconf/locking/level2oplocks.xml @@ -0,0 +1,39 @@ + + level2 oplocks (S) + This parameter controls whether Samba supports + level2 (read-only) oplocks on a share. + + Level2, or read-only oplocks allow Windows NT clients + that have an oplock on a file to downgrade from a read-write oplock + to a read-only oplock once a second client opens the file (instead + of releasing all oplocks on a second open, as in traditional, + exclusive oplocks). This allows all openers of the file that + support level2 oplocks to cache the file for read-ahead only (ie. + they may not cache writes or lock requests) and increases performance + for many accesses of files that are not commonly written (such as + application .EXE files). + + Once one of the clients which have a read-only oplock + writes to the file all clients are notified (no reply is needed + or waited for) and told to break their oplocks to "none" and + delete any read-ahead caches. + + It is recommended that this parameter be turned on + to speed access to shared executables. + + For more discussions on level2 oplocks see the CIFS spec. + + Currently, if kernel + oplocks are supported then level2 oplocks are + not granted (even if this parameter is set to yes). + Note also, the oplocks + parameter must be set to yes on this share in order for + this parameter to have any effect. + + See also the oplocks + and kernel oplocks + parameters. + + Default: level2 oplocks = yes + + diff --git a/docs/docbook/smbdotconf/locking/locking.xml b/docs/docbook/smbdotconf/locking/locking.xml new file mode 100644 index 0000000000..aa27027a11 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/locking.xml @@ -0,0 +1,25 @@ + + locking (S) + This controls whether or not locking will be + performed by the server in response to lock requests from the + client. + + If locking = no, all lock and unlock + requests will appear to succeed and all lock queries will report + that the file in question is available for locking. + + If locking = yes, real locking will be performed + by the server. + + This option may be useful for read-only + filesystems which may not need locking (such as + CDROM drives), although setting this parameter of no + is not really recommended even in this case. + + Be careful about disabling locking either globally or in a + specific service, as lack of locking may result in data corruption. + You should never need to set this parameter. + + Default: locking = yes + + diff --git a/docs/docbook/smbdotconf/locking/lockspincount.xml b/docs/docbook/smbdotconf/locking/lockspincount.xml new file mode 100644 index 0000000000..1ee1aab4d4 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/lockspincount.xml @@ -0,0 +1,15 @@ + + lock spin count (G) + This parameter controls the number of times + that smbd should attempt to gain a byte range lock on the + behalf of a client request. Experiments have shown that + Windows 2k servers do not reply with a failure if the lock + could not be immediately granted, but try a few more times + in case the lock could later be aquired. This behavior + is used to support PC database formats such as MS Access + and FoxPro. + + + Default: lock spin count = 2 + + diff --git a/docs/docbook/smbdotconf/locking/lockspintime.xml b/docs/docbook/smbdotconf/locking/lockspintime.xml new file mode 100644 index 0000000000..4d3ea1bdc4 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/lockspintime.xml @@ -0,0 +1,11 @@ + + lock spin time (G) + The time in microseconds that smbd should + pause before attempting to gain a failed lock. See + lock spin + count for more details. + + + Default: lock spin time = 10 + + diff --git a/docs/docbook/smbdotconf/locking/oplockbreakwaittime.xml b/docs/docbook/smbdotconf/locking/oplockbreakwaittime.xml new file mode 100644 index 0000000000..5e08200a33 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/oplockbreakwaittime.xml @@ -0,0 +1,16 @@ + + oplock break wait time (G) + This is a tuning parameter added due to bugs in + both Windows 9x and WinNT. If Samba responds to a client too + quickly when that client issues an SMB that can cause an oplock + break request, then the network client can fail and not respond + to the break request. This tuning parameter (which is set in milliseconds) + is the amount of time Samba will wait before sending an oplock break + request to such (broken) clients. + + DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ + AND UNDERSTOOD THE SAMBA OPLOCK CODE. + + Default: oplock break wait time = 0 + + diff --git a/docs/docbook/smbdotconf/locking/oplockcontentionlimit.xml b/docs/docbook/smbdotconf/locking/oplockcontentionlimit.xml new file mode 100644 index 0000000000..fd3b45d0b1 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/oplockcontentionlimit.xml @@ -0,0 +1,19 @@ + + oplock contention limit (S) + This is a very advanced + smbd(8) tuning option to + improve the efficiency of the granting of oplocks under multiple + client contention for the same file. + + In brief it specifies a number, which causes smbd + 8not to grant an oplock even when requested + if the approximate number of clients contending for an oplock on the same file goes over this + limit. This causes smbd to behave in a similar + way to Windows NT. + + DO NOT CHANGE THIS PARAMETER UNLESS YOU HAVE READ + AND UNDERSTOOD THE SAMBA OPLOCK CODE. + + Default: oplock contention limit = 2 + + diff --git a/docs/docbook/smbdotconf/locking/oplocks.xml b/docs/docbook/smbdotconf/locking/oplocks.xml new file mode 100644 index 0000000000..071786f35c --- /dev/null +++ b/docs/docbook/smbdotconf/locking/oplocks.xml @@ -0,0 +1,27 @@ + + oplocks (S) + This boolean option tells smbd whether to + issue oplocks (opportunistic locks) to file open requests on this + share. The oplock code can dramatically (approx. 30% or more) improve + the speed of access to files on Samba servers. It allows the clients + to aggressively cache files locally and you may want to disable this + option for unreliable network environments (it is turned on by + default in Windows NT Servers). For more information see the file + Speed.txt in the Samba docs/ + directory. + + Oplocks may be selectively turned off on certain files with a + share. See the + veto oplock files parameter. On some systems + oplocks are recognized by the underlying operating system. This + allows data synchronization between all access to oplocked files, + whether it be via Samba or NFS or a local UNIX process. See the + kernel oplocks parameter for details. + + See also the kernel + oplocks and + level2 oplocks parameters. + + Default: oplocks = yes + + diff --git a/docs/docbook/smbdotconf/locking/posixlocking.xml b/docs/docbook/smbdotconf/locking/posixlocking.xml new file mode 100644 index 0000000000..4f2e2d215b --- /dev/null +++ b/docs/docbook/smbdotconf/locking/posixlocking.xml @@ -0,0 +1,14 @@ + + posix locking (S) + The smbd + 8 + daemon maintains an database of file locks obtained by SMB clients. + The default behavior is to map this internal database to POSIX + locks. This means that file locks obtained by SMB clients are + consistent with those seen by POSIX compliant applications accessing + the files via a non-SMB method (e.g. NFS or local file access). + You should never need to disable this parameter. + + Default: posix locking = yes + + diff --git a/docs/docbook/smbdotconf/locking/sharemodes.xml b/docs/docbook/smbdotconf/locking/sharemodes.xml new file mode 100644 index 0000000000..c789ed0fb2 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/sharemodes.xml @@ -0,0 +1,26 @@ + + share modes (S) + This enables or disables the honoring of + the share modes during a file open. These + modes are used by clients to gain exclusive read or write access + to a file. + + These open modes are not directly supported by UNIX, so + they are simulated using shared memory, or lock files if your + UNIX doesn't support shared memory (almost all do). + + The share modes that are enabled by this option are + DENY_DOS, DENY_ALL, + DENY_READ, DENY_WRITE, + DENY_NONE and DENY_FCB. + + + This option gives full share compatibility and enabled + by default. + + You should NEVER turn this parameter + off as many Windows applications will break if you do so. + + Default: share modes = yes + + diff --git a/docs/docbook/smbdotconf/locking/strictlocking.xml b/docs/docbook/smbdotconf/locking/strictlocking.xml new file mode 100644 index 0000000000..b67ae47736 --- /dev/null +++ b/docs/docbook/smbdotconf/locking/strictlocking.xml @@ -0,0 +1,17 @@ + + strict locking (S) + This is a boolean that controls the handling of + file locking in the server. When this is set to yes + the server will check every read and write access for file locks, and + deny access if locks exist. This can be slow on some systems. + + When strict locking is no the server does file + lock checks only when the client explicitly asks for them. + + Well-behaved clients always ask for lock checks when it + is important, so in the vast majority of cases strict + locking = no is preferable. + + Default: strict locking = no + + diff --git a/docs/docbook/smbdotconf/logging/debughirestimestamp.xml b/docs/docbook/smbdotconf/logging/debughirestimestamp.xml new file mode 100644 index 0000000000..a5f40b73ca --- /dev/null +++ b/docs/docbook/smbdotconf/logging/debughirestimestamp.xml @@ -0,0 +1,14 @@ + + debug hires timestamp (G) + Sometimes the timestamps in the log messages + are needed with a resolution of higher that seconds, this + boolean parameter adds microsecond resolution to the timestamp + message header when turned on. + + Note that the parameter + debug timestamp must be on for this to have an + effect. + + Default: debug hires timestamp = no + + diff --git a/docs/docbook/smbdotconf/logging/debuglevel.xml b/docs/docbook/smbdotconf/logging/debuglevel.xml new file mode 100644 index 0000000000..99153fa853 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/debuglevel.xml @@ -0,0 +1,6 @@ + + debuglevel (G) + Synonym for + log level. + + diff --git a/docs/docbook/smbdotconf/logging/debugpid.xml b/docs/docbook/smbdotconf/logging/debugpid.xml new file mode 100644 index 0000000000..829e168412 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/debugpid.xml @@ -0,0 +1,13 @@ + + debug pid (G) + When using only one log file for more then one + forked smbd-process there may be hard to follow which process + outputs which message. This boolean parameter is adds the process-id + to the timestamp message headers in the logfile when turned on. + + Note that the parameter + debug timestamp must be on for this to have an + effect. + + Default: debug pid = no + diff --git a/docs/docbook/smbdotconf/logging/debugtimestamp.xml b/docs/docbook/smbdotconf/logging/debugtimestamp.xml new file mode 100644 index 0000000000..1265c1d21b --- /dev/null +++ b/docs/docbook/smbdotconf/logging/debugtimestamp.xml @@ -0,0 +1,10 @@ + + debug timestamp (G) + Samba debug log messages are timestamped + by default. If you are running at a high + debug level these timestamps + can be distracting. This boolean parameter allows timestamping + to be turned off. + + Default: debug timestamp = yes + diff --git a/docs/docbook/smbdotconf/logging/debuguid.xml b/docs/docbook/smbdotconf/logging/debuguid.xml new file mode 100644 index 0000000000..9b0786d6b3 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/debuguid.xml @@ -0,0 +1,13 @@ + + debug uid (G) + Samba is sometimes run as root and sometime + run as the connected user, this boolean parameter inserts the + current euid, egid, uid and gid to the timestamp message headers + in the log file if turned on. + + Note that the parameter + debug timestamp must be on for this to have an + effect. + + Default: debug uid = no + diff --git a/docs/docbook/smbdotconf/logging/logfile.xml b/docs/docbook/smbdotconf/logging/logfile.xml new file mode 100644 index 0000000000..6f176ef02b --- /dev/null +++ b/docs/docbook/smbdotconf/logging/logfile.xml @@ -0,0 +1,11 @@ + + log file (G) + This option allows you to override the name + of the Samba log file (also known as the debug file). + + This option takes the standard substitutions, allowing + you to have separate log files for each user or machine. + + Example: log file = /usr/local/samba/var/log.%m + + diff --git a/docs/docbook/smbdotconf/logging/loglevel.xml b/docs/docbook/smbdotconf/logging/loglevel.xml new file mode 100644 index 0000000000..610dc96812 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/loglevel.xml @@ -0,0 +1,15 @@ + + log level (G) + The value of the parameter (a astring) allows + the debug level (logging level) to be specified in the + smb.conf file. This parameter has been + extended since the 2.2.x series, now it allow to specify the debug + level for multiple debug classes. This is to give greater + flexibility in the configuration of the system. + + The default will be the log level specified on + the command line or level zero if none was specified. + + Example: log level = 3 passdb:5 auth:10 winbind:2 + + diff --git a/docs/docbook/smbdotconf/logging/maxlogsize.xml b/docs/docbook/smbdotconf/logging/maxlogsize.xml new file mode 100644 index 0000000000..117410b18c --- /dev/null +++ b/docs/docbook/smbdotconf/logging/maxlogsize.xml @@ -0,0 +1,13 @@ + + max log size (G) + This option (an integer in kilobytes) specifies + the max size the log file should grow to. Samba periodically checks + the size and if it is exceeded it will rename the file, adding + a .old extension. + + A size of 0 means no limit. + + Default: max log size = 5000 + Example: max log size = 1000 + + diff --git a/docs/docbook/smbdotconf/logging/syslog.xml b/docs/docbook/smbdotconf/logging/syslog.xml new file mode 100644 index 0000000000..ac098e690a --- /dev/null +++ b/docs/docbook/smbdotconf/logging/syslog.xml @@ -0,0 +1,17 @@ + + syslog (G) + This parameter maps how Samba debug messages + are logged onto the system syslog logging levels. Samba debug + level zero maps onto syslog LOG_ERR, debug + level one maps onto LOG_WARNING, debug level + two maps onto LOG_NOTICE, debug level three + maps onto LOG_INFO. All higher levels are mapped to + LOG_DEBUG. + + This parameter sets the threshold for sending messages + to syslog. Only messages with debug level less than this value + will be sent to syslog. + + Default: syslog = 1 + + diff --git a/docs/docbook/smbdotconf/logging/syslogonly.xml b/docs/docbook/smbdotconf/logging/syslogonly.xml new file mode 100644 index 0000000000..a955306fe0 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/syslogonly.xml @@ -0,0 +1,9 @@ + + syslog only (G) + If this parameter is set then Samba debug + messages are logged into the system syslog only, and not to + the debug log files. + + Default: syslog only = no + + diff --git a/docs/docbook/smbdotconf/logging/timestamplogs.xml b/docs/docbook/smbdotconf/logging/timestamplogs.xml new file mode 100644 index 0000000000..5f5f42d738 --- /dev/null +++ b/docs/docbook/smbdotconf/logging/timestamplogs.xml @@ -0,0 +1,6 @@ + + timestamp logs (G) + Synonym for + debug timestamp. + + diff --git a/docs/docbook/smbdotconf/logon/abortshutdownscript.xml b/docs/docbook/smbdotconf/logon/abortshutdownscript.xml new file mode 100644 index 0000000000..89fd9186bb --- /dev/null +++ b/docs/docbook/smbdotconf/logon/abortshutdownscript.xml @@ -0,0 +1,13 @@ + + abort shutdown script (G) + This parameter only exists in the HEAD cvs branch + This a full path name to a script called by smbd + 8 that + should stop a shutdown procedure issued by the shutdown script. + + This command will be run as user. + + Default: None. + Example: abort shutdown script = /sbin/shutdown -c + + diff --git a/docs/docbook/smbdotconf/logon/addgroupscript.xml b/docs/docbook/smbdotconf/logon/addgroupscript.xml new file mode 100644 index 0000000000..67441a1645 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/addgroupscript.xml @@ -0,0 +1,14 @@ +add group script (G) + This is the full pathname to a script that will + be run AS ROOT by smbd + 8 when a new group is + requested. It will expand any + %g to the group name passed. + This script is only useful for installations using the + Windows NT domain administration tools. The script is + free to create a group with an arbitrary name to + circumvent unix group name restrictions. In that case + the script must print the numeric gid of the created + group on stdout. + + diff --git a/docs/docbook/smbdotconf/logon/addmachinescript.xml b/docs/docbook/smbdotconf/logon/addmachinescript.xml new file mode 100644 index 0000000000..fdc69c9490 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/addmachinescript.xml @@ -0,0 +1,18 @@ + + add machine script (G) + This is the full pathname to a script that will + be run by smbd + 8 when a machine is added + to it's domain using the administrator username and password method. + + This option is only required when using sam back-ends tied to the + Unix uid method of RID calculation such as smbpasswd. This option is only + available in Samba 3.0. + + Default: add machine script = <empty string> + + + Example: add machine script = /usr/sbin/adduser -n -g machines -c Machine -d /dev/null -s /bin/false %u + + + diff --git a/docs/docbook/smbdotconf/logon/adduserscript.xml b/docs/docbook/smbdotconf/logon/adduserscript.xml new file mode 100644 index 0000000000..3afea231a5 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/adduserscript.xml @@ -0,0 +1,49 @@ + + add user script (G) + This is the full pathname to a script that will + be run AS ROOT by smbd + 8 under special circumstances described below. + + Normally, a Samba server requires that UNIX users are + created for all users accessing files on this server. For sites + that use Windows NT account databases as their primary user database + creating these users and keeping the user list in sync with the + Windows NT PDC is an onerous task. This option allows smbd to create the required UNIX users + ON DEMAND when a user accesses the Samba server. + + In order to use this option, smbd + 8 must NOT be set to security = share + and add user script + must be set to a full pathname for a script that will create a UNIX + user given one argument of %u, which expands into + the UNIX user name to create. + + When the Windows user attempts to access the Samba server, + at login (session setup in the SMB protocol) time, smbd + 8 contacts the password server and + attempts to authenticate the given user with the given password. If the + authentication succeeds then smbd + attempts to find a UNIX user in the UNIX password database to map the + Windows user into. If this lookup fails, and add user script + is set then smbd will + call the specified script AS ROOT, expanding + any %u argument to be the user name to create. + + If this script successfully creates the user then smbd + will continue on as though the UNIX user + already existed. In this way, UNIX users are dynamically created to + match existing Windows NT accounts. + + See also + security, + password server, + delete user + script. + + Default: add user script = <empty string> + + + Example: add user script = /usr/local/samba/bin/add_user + %u + + diff --git a/docs/docbook/smbdotconf/logon/addusertogroupscript.xml b/docs/docbook/smbdotconf/logon/addusertogroupscript.xml new file mode 100644 index 0000000000..fe8be5b504 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/addusertogroupscript.xml @@ -0,0 +1,16 @@ + + add user to group script (G) + Full path to the script that will be called when + a user is added to a group using the Windows NT domain administration + tools. It will be run by smbd + 8 AS ROOT. + Any %g will be replaced with the group name and + any %u will be replaced with the user name. + + + Default: add user to group script = + + Example: add user to group script = /usr/sbin/adduser %u %g + + + diff --git a/docs/docbook/smbdotconf/logon/deletegroupscript.xml b/docs/docbook/smbdotconf/logon/deletegroupscript.xml new file mode 100644 index 0000000000..02c413115a --- /dev/null +++ b/docs/docbook/smbdotconf/logon/deletegroupscript.xml @@ -0,0 +1,8 @@ +delete group script (G) + This is the full pathname to a script that will + be run AS ROOT smbd + 8 when a group is requested to be deleted. + It will expand any %g to the group name passed. + This script is only useful for installations using the Windows NT domain administration tools. + + diff --git a/docs/docbook/smbdotconf/logon/deleteuserfromgroupscript.xml b/docs/docbook/smbdotconf/logon/deleteuserfromgroupscript.xml new file mode 100644 index 0000000000..bb1c5136c1 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/deleteuserfromgroupscript.xml @@ -0,0 +1,16 @@ + + delete user from group script (G) + Full path to the script that will be called when + a user is removed from a group using the Windows NT domain administration + tools. It will be run by smbd + 8 AS ROOT. + Any %g will be replaced with the group name and + any %u will be replaced with the user name. + + + Default: delete user from group script = + + Example: delete user from group script = /usr/sbin/deluser %u %g + + + diff --git a/docs/docbook/smbdotconf/logon/deleteuserscript.xml b/docs/docbook/smbdotconf/logon/deleteuserscript.xml new file mode 100644 index 0000000000..afb75dbe77 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/deleteuserscript.xml @@ -0,0 +1,21 @@ + + delete user script (G) + This is the full pathname to a script that will + be run by smbd + 8 when managing users + with remote RPC (NT) tools. + + + This script is called when a remote client removes a user + from the server, normally using 'User Manager for Domains' or + rpcclient. + + + This script should delete the given UNIX username. + + + Default: delete user script = <empty string> + + Example: delete user script = /usr/local/samba/bin/del_user + %u + diff --git a/docs/docbook/smbdotconf/logon/domainlogons.xml b/docs/docbook/smbdotconf/logon/domainlogons.xml new file mode 100644 index 0000000000..9a2f432f7d --- /dev/null +++ b/docs/docbook/smbdotconf/logon/domainlogons.xml @@ -0,0 +1,12 @@ + + domain logons (G) + If set to yes, the Samba server will serve + Windows 95/98 Domain logons for the + workgroup it is in. Samba 2.2 + has limited capability to act as a domain controller for Windows + NT 4 Domains. For more details on setting up this feature see + the Samba-PDC-HOWTO included in the htmldocs/ + directory shipped with the source code. + + Default: domain logons = no + diff --git a/docs/docbook/smbdotconf/logon/logondrive.xml b/docs/docbook/smbdotconf/logon/logondrive.xml new file mode 100644 index 0000000000..d0aa4d7456 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/logondrive.xml @@ -0,0 +1,13 @@ + + logon drive (G) + This parameter specifies the local path to + which the home directory will be connected (see logon home) + and is only used by NT Workstations. + + Note that this option is only useful if Samba is set up as a + logon server. + + Default: logon drive = z: + Example: logon drive = h: + + diff --git a/docs/docbook/smbdotconf/logon/logonhome.xml b/docs/docbook/smbdotconf/logon/logonhome.xml new file mode 100644 index 0000000000..ec19c54043 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/logonhome.xml @@ -0,0 +1,40 @@ + + logon home (G) + This parameter specifies the home directory + location when a Win95/98 or NT Workstation logs into a Samba PDC. + It allows you to do + + C:\> NET USE H: /HOME + + + from a command prompt, for example. + + This option takes the standard substitutions, allowing + you to have separate logon scripts for each user or machine. + + This parameter can be used with Win9X workstations to ensure + that roaming profiles are stored in a subdirectory of the user's + home directory. This is done in the following way: + + logon home = \\%N\%U\profile + + This tells Samba to return the above string, with + substitutions made when a client requests the info, generally + in a NetUserGetInfo request. Win9X clients truncate the info to + \\server\share when a user does net use /home + but use the whole string when dealing with profiles. + + Note that in prior versions of Samba, the + logon path was returned rather than + logon home. This broke net use + /home but allowed profiles outside the home directory. + The current implementation is correct, and can be used for + profiles if you use the above trick. + + This option is only useful if Samba is set up as a logon + server. + + Default: logon home = "\\%N\%U" + Example: logon home = "\\remote_smb_server\%U" + + diff --git a/docs/docbook/smbdotconf/logon/logonpath.xml b/docs/docbook/smbdotconf/logon/logonpath.xml new file mode 100644 index 0000000000..04a2777862 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/logonpath.xml @@ -0,0 +1,45 @@ + + logon path (G) + This parameter specifies the home directory + where roaming profiles (NTuser.dat etc files for Windows NT) are + stored. Contrary to previous versions of these manual pages, it has + nothing to do with Win 9X roaming profiles. To find out how to + handle roaming profiles for Win 9X system, see the + logon home parameter. + + This option takes the standard substitutions, allowing you + to have separate logon scripts for each user or machine. It also + specifies the directory from which the "Application Data", + (desktop, start menu, + network neighborhood, programs + and other folders, and their contents, are loaded and displayed on + your Windows NT client. + + The share and the path must be readable by the user for + the preferences and directories to be loaded onto the Windows NT + client. The share must be writeable when the user logs in for the first + time, in order that the Windows NT client can create the NTuser.dat + and other directories. + + Thereafter, the directories and any of the contents can, + if required, be made read-only. It is not advisable that the + NTuser.dat file be made read-only - rename it to NTuser.man to + achieve the desired effect (a MANdatory + profile). + + Windows clients can sometimes maintain a connection to + the [homes] share, even though there is no user logged in. + Therefore, it is vital that the logon path does not include a + reference to the homes share (i.e. setting this parameter to + \%N\%U\profile_path will cause problems). + + This option takes the standard substitutions, allowing + you to have separate logon scripts for each user or machine. + + Note that this option is only useful if Samba is set up + as a logon server. + + Default: logon path = \\%N\%U\profile + Example: logon path = \\PROFILESERVER\PROFILE\%U + + diff --git a/docs/docbook/smbdotconf/logon/logonscript.xml b/docs/docbook/smbdotconf/logon/logonscript.xml new file mode 100644 index 0000000000..842cf927d2 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/logonscript.xml @@ -0,0 +1,39 @@ + + logon script (G) + This parameter specifies the batch file (.bat) or + NT command file (.cmd) to be downloaded and run on a machine when + a user successfully logs in. The file must contain the DOS + style CR/LF line endings. Using a DOS-style editor to create the + file is recommended. + + The script must be a relative path to the [netlogon] + service. If the [netlogon] service specifies a + path of /usr/local/samba/netlogon + , and logon script = STARTUP.BAT, then + the file that will be downloaded is: + + /usr/local/samba/netlogon/STARTUP.BAT + + The contents of the batch file are entirely your choice. A + suggested command would be to add NET TIME \\SERVER /SET + /YES, to force every machine to synchronize clocks with + the same time server. Another use would be to add NET USE + U: \\SERVER\UTILS for commonly used utilities, or + NET USE Q: \\SERVER\ISO9001_QA for example. + + Note that it is particularly important not to allow write + access to the [netlogon] share, or to grant users write permission + on the batch files in a secure environment, as this would allow + the batch files to be arbitrarily modified and security to be + breached. + + This option takes the standard substitutions, allowing you + to have separate logon scripts for each user or machine. + + This option is only useful if Samba is set up as a logon + server. + + Default: no logon script defined + Example: logon script = scripts\%U.bat + + diff --git a/docs/docbook/smbdotconf/logon/shutdownscript.xml b/docs/docbook/smbdotconf/logon/shutdownscript.xml new file mode 100644 index 0000000000..ac286393b5 --- /dev/null +++ b/docs/docbook/smbdotconf/logon/shutdownscript.xml @@ -0,0 +1,42 @@ + + shutdown script (G) + This parameter only exists in the HEAD cvs branch + This a full path name to a script called by + smbd(8) that + should start a shutdown procedure. + + This command will be run as the user connected to the + server. + + %m %t %r %f parameters are expanded + %m will be substituted with the + shutdown message sent to the server. + %t will be substituted with the + number of seconds to wait before effectively starting the + shutdown procedure. + %r will be substituted with the + switch -r. It means reboot after shutdown + for NT. + + %f will be substituted with the + switch -f. It means force the shutdown + even if applications do not respond for NT. + + Default: None. + Example: abort shutdown script = /usr/local/samba/sbin/shutdown %m %t %r %f + Shutdown script example: + +#!/bin/bash + +$time=0 +let "time/60" +let "time++" + +/sbin/shutdown $3 $4 +$time $1 & + + Shutdown does not return so we need to launch it in background. + + + See also abort shutdown script. + + diff --git a/docs/docbook/smbdotconf/man.xsl b/docs/docbook/smbdotconf/man.xsl new file mode 100644 index 0000000000..a7ae76bbd8 --- /dev/null +++ b/docs/docbook/smbdotconf/man.xsl @@ -0,0 +1,159 @@ + + + + + + + + + + + + + + + + + + : + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .\"Generated by db2man.xsl. Don't modify this, modify the source. +.de Sh \" Subsection +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.TH " + + " + + " + + " " + + " " + + " + + + + + + + + + + + + + + + + .nf + + .fi + + + + \fB + + \fR + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/docbook/smbdotconf/misc/addsharecommand.xml b/docs/docbook/smbdotconf/misc/addsharecommand.xml new file mode 100644 index 0000000000..233d3e7dc4 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/addsharecommand.xml @@ -0,0 +1,51 @@ + + add share command (G) + Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + add share command is used to define an + external program or script which will add a new service definition + to smb.conf. In order to successfully + execute the add share command, smbd + requires that the administrator be connected using a root account (i.e. + uid == 0). + + + + When executed, smbd will automatically invoke the + add share command with four parameters. + + + + configFile - the location + of the global smb.conf file. + + + shareName - the name of the new + share. + + + pathName - path to an **existing** + directory on disk. + + + comment - comment string to associate + with the new share. + + + + + This parameter is only used for add file shares. To add printer shares, + see the addprinter + command. + + + + See also change share + command, delete share + command. + + + Default: none + Example: add share command = /usr/local/bin/addshare + + diff --git a/docs/docbook/smbdotconf/misc/autoservices.xml b/docs/docbook/smbdotconf/misc/autoservices.xml new file mode 100644 index 0000000000..d137f650f8 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/autoservices.xml @@ -0,0 +1,6 @@ + + auto services (G) + This is a synonym for the + preload. + + diff --git a/docs/docbook/smbdotconf/misc/available.xml b/docs/docbook/smbdotconf/misc/available.xml new file mode 100644 index 0000000000..025c1c06fb --- /dev/null +++ b/docs/docbook/smbdotconf/misc/available.xml @@ -0,0 +1,11 @@ + + available (S) + This parameter lets you "turn off" a service. If + available = no, then ALL + attempts to connect to the service will fail. Such failures are + logged. + + Default: available = yes + + + diff --git a/docs/docbook/smbdotconf/misc/changesharecommand.xml b/docs/docbook/smbdotconf/misc/changesharecommand.xml new file mode 100644 index 0000000000..3fb494c513 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/changesharecommand.xml @@ -0,0 +1,50 @@ + + change share command (G) + Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + change share command is used to define an + external program or script which will modify an existing service definition + in smb.conf. In order to successfully + execute the change share command, smbd + requires that the administrator be connected using a root account (i.e. + uid == 0). + + + + When executed, smbd will automatically invoke the + change share command with four parameters. + + + + configFile - the location + of the global smb.conf file. + + + shareName - the name of the new + share. + + + pathName - path to an **existing** + directory on disk. + + + comment - comment string to associate + with the new share. + + + + + This parameter is only used modify existing file shares definitions. To modify + printer shares, use the "Printers..." folder as seen when browsing the Samba host. + + + + See also add share + command, delete + share command. + + + Default: none + Example: change share command = /usr/local/bin/addshare + + diff --git a/docs/docbook/smbdotconf/misc/configfile.xml b/docs/docbook/smbdotconf/misc/configfile.xml new file mode 100644 index 0000000000..3edf611b55 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/configfile.xml @@ -0,0 +1,21 @@ + + config file (G) + This allows you to override the config file + to use, instead of the default (usually smb.conf). + There is a chicken and egg problem here as this option is set + in the config file! + + For this reason, if the name of the config file has changed + when the parameters are loaded then it will reload them from + the new config file. + + This option takes the usual substitutions, which can + be very useful. + + If the config file doesn't exist then it won't be loaded + (allowing you to special case the config files of just a few + clients). + + Example: config file = /usr/local/samba/lib/smb.conf.%m + + diff --git a/docs/docbook/smbdotconf/misc/copy.xml b/docs/docbook/smbdotconf/misc/copy.xml new file mode 100644 index 0000000000..a7945af8ae --- /dev/null +++ b/docs/docbook/smbdotconf/misc/copy.xml @@ -0,0 +1,15 @@ + + copy (S) + This parameter allows you to "clone" service + entries. The specified service is simply duplicated under the + current service's name. Any parameters specified in the current + section will override those in the section being copied. + + This feature lets you set up a 'template' service and + create similar services easily. Note that the service being + copied must occur earlier in the configuration file than the + service doing the copying. + + Default: no value + Example: copy = otherservice + diff --git a/docs/docbook/smbdotconf/misc/default.xml b/docs/docbook/smbdotconf/misc/default.xml new file mode 100644 index 0000000000..c396d1947b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/default.xml @@ -0,0 +1,5 @@ + + default (G) + A synonym for + default service. + diff --git a/docs/docbook/smbdotconf/misc/defaultservice.xml b/docs/docbook/smbdotconf/misc/defaultservice.xml new file mode 100644 index 0000000000..7aeedb177a --- /dev/null +++ b/docs/docbook/smbdotconf/misc/defaultservice.xml @@ -0,0 +1,36 @@ + + default service (G) + This parameter specifies the name of a service + which will be connected to if the service actually requested cannot + be found. Note that the square brackets are NOT + given in the parameter value (see example below). + + There is no default value for this parameter. If this + parameter is not given, attempting to connect to a nonexistent + service results in an error. + + Typically the default service would be a + guest ok, + read-only service. + + Also note that the apparent service name will be changed + to equal that of the requested service, this is very useful as it + allows you to use macros like %S to make + a wildcard service. + + Note also that any "_" characters in the name of the service + used in the default service will get mapped to a "/". This allows for + interesting things. + + + Example: + + +[global] + default service = pub + +[pub] + path = /%S + + + diff --git a/docs/docbook/smbdotconf/misc/deletereadonly.xml b/docs/docbook/smbdotconf/misc/deletereadonly.xml new file mode 100644 index 0000000000..8e86b5b00b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/deletereadonly.xml @@ -0,0 +1,11 @@ + + delete readonly (S) + This parameter allows readonly files to be deleted. + This is not normal DOS semantics, but is allowed by UNIX. + + This option may be useful for running applications such + as rcs, where UNIX file ownership prevents changing file + permissions, and DOS semantics prevent deletion of a read only file. + + Default: delete readonly = no + diff --git a/docs/docbook/smbdotconf/misc/deletesharecommand.xml b/docs/docbook/smbdotconf/misc/deletesharecommand.xml new file mode 100644 index 0000000000..c3481c86ec --- /dev/null +++ b/docs/docbook/smbdotconf/misc/deletesharecommand.xml @@ -0,0 +1,44 @@ + + delete share command (G) + Samba 2.2.0 introduced the ability to dynamically + add and delete shares via the Windows NT 4.0 Server Manager. The + delete share command is used to define an + external program or script which will remove an existing service + definition from smb.conf. In order to successfully + execute the delete share command, smbd + requires that the administrator be connected using a root account (i.e. + uid == 0). + + + + When executed, smbd will automatically invoke the + delete share command with two parameters. + + + + configFile - the location + of the global smb.conf file. + + + shareName - the name of + the existing service. + + + + + This parameter is only used to remove file shares. To delete printer shares, + see the deleteprinter + command. + + + + See also add share + command, change + share command. + + + Default: none + Example: delete share command = /usr/local/bin/delshare + + + diff --git a/docs/docbook/smbdotconf/misc/dfreecommand.xml b/docs/docbook/smbdotconf/misc/dfreecommand.xml new file mode 100644 index 0000000000..c71ec8e00b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dfreecommand.xml @@ -0,0 +1,50 @@ + + dfree command (G) + The dfree command setting should + only be used on systems where a problem occurs with the internal + disk space calculations. This has been known to happen with Ultrix, + but may occur with other operating systems. The symptom that was + seen was an error of "Abort Retry Ignore" at the end of each + directory listing. + + This setting allows the replacement of the internal routines to + calculate the total disk space and amount available with an external + routine. The example below gives a possible script that might fulfill + this function. + + The external program will be passed a single parameter indicating + a directory in the filesystem being queried. This will typically consist + of the string ./. The script should return two + integers in ASCII. The first should be the total disk space in blocks, + and the second should be the number of available blocks. An optional + third return value can give the block size in bytes. The default + blocksize is 1024 bytes. + + Note: Your script should NOT be setuid or + setgid and should be owned by (and writeable only by) root! + + Default: By default internal routines for + determining the disk capacity and remaining space will be used. + + + Example: dfree command = /usr/local/samba/bin/dfree + + + Where the script dfree (which must be made executable) could be: + + +#!/bin/sh +df $1 | tail -1 | awk '{print $2" "$4}' + + + or perhaps (on Sys V based systems): + + +#!/bin/sh +/usr/bin/df -k $1 | tail -1 | awk '{print $3" "$5}' + + + Note that you may have to replace the command names + with full path names on some systems. + + diff --git a/docs/docbook/smbdotconf/misc/dontdescend.xml b/docs/docbook/smbdotconf/misc/dontdescend.xml new file mode 100644 index 0000000000..8136f293df --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dontdescend.xml @@ -0,0 +1,18 @@ + + dont descend (S) + There are certain directories on some systems + (e.g., the /proc tree under Linux) that are either not + of interest to clients or are infinitely deep (recursive). This + parameter allows you to specify a comma-delimited list of directories + that the server should always show as empty. + + Note that Samba can be very fussy about the exact format + of the "dont descend" entries. For example you may need + ./proc instead of just /proc. + Experimentation is the best policy :-) + + Default: none (i.e., all directories are OK + to descend) + Example: dont descend = /proc,/dev + + diff --git a/docs/docbook/smbdotconf/misc/dosfilemode.xml b/docs/docbook/smbdotconf/misc/dosfilemode.xml new file mode 100644 index 0000000000..e8aec3b78d --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfilemode.xml @@ -0,0 +1,16 @@ + + dos filemode (S) + The default behavior in Samba is to provide + UNIX-like behavior where only the owner of a file/directory is + able to change the permissions on it. However, this behavior + is often confusing to DOS/Windows users. Enabling this parameter + allows a user who has write access to the file (by whatever + means) to modify the permissions on it. Note that a user + belonging to the group owning the file will not be allowed to + change permissions if the group is only granted read access. + Ownership of the file/directory is not changed, only the permissions + are modified. + + Default: dos filemode = no + + diff --git a/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml b/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml new file mode 100644 index 0000000000..bc82582c87 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfiletimeresolution.xml @@ -0,0 +1,23 @@ + + dos filetime resolution (S) + Under the DOS and Windows FAT filesystem, the finest + granularity on time resolution is two seconds. Setting this parameter + for a share causes Samba to round the reported time down to the + nearest two second boundary when a query call that requires one second + resolution is made to smbd + 8. + + This option is mainly used as a compatibility option for Visual + C++ when used against Samba shares. If oplocks are enabled on a + share, Visual C++ uses two different time reading calls to check if a + file has changed since it was last read. One of these calls uses a + one-second granularity, the other uses a two second granularity. As + the two second call rounds any odd second down, then if the file has a + timestamp of an odd number of seconds then the two timestamps will not + match and Visual C++ will keep reporting the file has changed. Setting + this option causes the two timestamps to match, and Visual C++ is + happy. + + Default: dos filetime resolution = no + + diff --git a/docs/docbook/smbdotconf/misc/dosfiletimes.xml b/docs/docbook/smbdotconf/misc/dosfiletimes.xml new file mode 100644 index 0000000000..d9b9f3b08b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/dosfiletimes.xml @@ -0,0 +1,14 @@ + + dos filetimes (S) + Under DOS and Windows, if a user can write to a + file they can change the timestamp on it. Under POSIX semantics, + only the owner of the file or root may change the timestamp. By + default, Samba runs with POSIX semantics and refuses to change the + timestamp on a file if the user smbd is acting + on behalf of is not the file owner. Setting this option to + yes allows DOS semantics and smbd + 8 will change the file + timestamp as DOS requires. + + Default: dos filetimes = no + diff --git a/docs/docbook/smbdotconf/misc/exec.xml b/docs/docbook/smbdotconf/misc/exec.xml new file mode 100644 index 0000000000..34963c90b2 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/exec.xml @@ -0,0 +1,5 @@ + + exec (S) + This is a synonym for + preexec. + diff --git a/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml b/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml new file mode 100644 index 0000000000..81773606ee --- /dev/null +++ b/docs/docbook/smbdotconf/misc/fakedirectorycreatetimes.xml @@ -0,0 +1,31 @@ + + fake directory create times (S) + NTFS and Windows VFAT file systems keep a create + time for all files and directories. This is not the same as the + ctime - status change time - that Unix keeps, so Samba by default + reports the earliest of the various times Unix does keep. Setting + this parameter for a share causes Samba to always report midnight + 1-1-1980 as the create time for directories. + + This option is mainly used as a compatibility option for + Visual C++ when used against Samba shares. Visual C++ generated + makefiles have the object directory as a dependency for each object + file, and a make rule to create the directory. Also, when NMAKE + compares timestamps it uses the creation time when examining a + directory. Thus the object directory will be created if it does not + exist, but once it does exist it will always have an earlier + timestamp than the object files it contains. + + However, Unix time semantics mean that the create time + reported by Samba will be updated whenever a file is created or + or deleted in the directory. NMAKE finds all object files in + the object directory. The timestamp of the last one built is then + compared to the timestamp of the object directory. If the + directory's timestamp if newer, then all object files + will be rebuilt. Enabling this option + ensures directories always predate their contents and an NMAKE build + will proceed as expected. + + Default: fake directory create times = no + + diff --git a/docs/docbook/smbdotconf/misc/followsymlinks.xml b/docs/docbook/smbdotconf/misc/followsymlinks.xml new file mode 100644 index 0000000000..88526da320 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/followsymlinks.xml @@ -0,0 +1,18 @@ + + follow symlinks (S) + This parameter allows the Samba administrator + to stop smbd + 8 from following symbolic + links in a particular share. Setting this + parameter to no prevents any file or directory + that is a symbolic link from being followed (the user will get an + error). This option is very useful to stop users from adding a + symbolic link to /etc/passwd in their home + directory for instance. However it will slow filename lookups + down slightly. + + This option is enabled (i.e. smbd will + follow symbolic links) by default. + + Default: follow symlinks = yes + diff --git a/docs/docbook/smbdotconf/misc/fstype.xml b/docs/docbook/smbdotconf/misc/fstype.xml new file mode 100644 index 0000000000..566bccb465 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/fstype.xml @@ -0,0 +1,14 @@ + + fstype (S) + This parameter allows the administrator to + configure the string that specifies the type of filesystem a share + is using that is reported by smbd + 8 when a client queries the filesystem type + for a share. The default type is NTFS for + compatibility with Windows NT but this can be changed to other + strings such as Samba or FAT + if required. + + Default: fstype = NTFS + Example: fstype = Samba + diff --git a/docs/docbook/smbdotconf/misc/hidelocalusers.xml b/docs/docbook/smbdotconf/misc/hidelocalusers.xml new file mode 100644 index 0000000000..d0468ead6b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/hidelocalusers.xml @@ -0,0 +1,7 @@ + + hide local users(G) + This parameter toggles the hiding of local UNIX + users (root, wheel, floppy, etc) from remote clients. + + Default: hide local users = no + diff --git a/docs/docbook/smbdotconf/misc/homedirmap.xml b/docs/docbook/smbdotconf/misc/homedirmap.xml new file mode 100644 index 0000000000..87a59204a2 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/homedirmap.xml @@ -0,0 +1,28 @@ + + homedir map (G) + Ifnis homedir + is yes, and smbd + 8 is also acting + as a Win95/98 logon server then this parameter + specifies the NIS (or YP) map from which the server for the user's + home directory should be extracted. At present, only the Sun + auto.home map format is understood. The form of the map is: + + username server:/some/file/system + + and the program will extract the servername from before + the first ':'. There should probably be a better parsing system + that copes with different map formats and also Amd (another + automounter) maps. + + NOTE :A working NIS client is required on + the system for this option to work. + + See also nis homedir + , domain logons + . + + Default: homedir map = <empty string> + Example: homedir map = amd.homedir + + diff --git a/docs/docbook/smbdotconf/misc/include.xml b/docs/docbook/smbdotconf/misc/include.xml new file mode 100644 index 0000000000..81230d4357 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/include.xml @@ -0,0 +1,14 @@ + + include (G) + This allows you to include one config file + inside another. The file is included literally, as though typed + in place. + + It takes the standard substitutions, except %u + , %P and %S. + + + Default: no file included + Example: include = /usr/local/samba/lib/admin_smb.conf + + diff --git a/docs/docbook/smbdotconf/misc/lockdir.xml b/docs/docbook/smbdotconf/misc/lockdir.xml new file mode 100644 index 0000000000..2c29b9b61c --- /dev/null +++ b/docs/docbook/smbdotconf/misc/lockdir.xml @@ -0,0 +1,5 @@ + + lock dir (G) + Synonym for + lock directory. + diff --git a/docs/docbook/smbdotconf/misc/lockdirectory.xml b/docs/docbook/smbdotconf/misc/lockdirectory.xml new file mode 100644 index 0000000000..7945f19864 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/lockdirectory.xml @@ -0,0 +1,11 @@ + + lock directory (G) + This option specifies the directory where lock + files will be placed. The lock files are used to implement the + max connections + option. + + Default: lock directory = ${prefix}/var/locks + Example: lock directory = /var/run/samba/locks + + diff --git a/docs/docbook/smbdotconf/misc/magicoutput.xml b/docs/docbook/smbdotconf/misc/magicoutput.xml new file mode 100644 index 0000000000..8208d5bd4c --- /dev/null +++ b/docs/docbook/smbdotconf/misc/magicoutput.xml @@ -0,0 +1,17 @@ + + magic output (S) + This parameter specifies the name of a file + which will contain output created by a magic script (see the + magic script + parameter below). + + Warning: If two clients use the same magic script + in the same directory the output file content + is undefined. + + Default: magic output = <magic script name>.out + + + Example: magic output = myfile.txt + + diff --git a/docs/docbook/smbdotconf/misc/magicscript.xml b/docs/docbook/smbdotconf/misc/magicscript.xml new file mode 100644 index 0000000000..73abb50fc5 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/magicscript.xml @@ -0,0 +1,28 @@ + + magic script (S) + This parameter specifies the name of a file which, + if opened, will be executed by the server when the file is closed. + This allows a UNIX script to be sent to the Samba host and + executed on behalf of the connected user. + + Scripts executed in this way will be deleted upon + completion assuming that the user has the appropriate level + of privilege and the file permissions allow the deletion. + + If the script generates output, output will be sent to + the file specified by the + magic output parameter (see above). + + Note that some shells are unable to interpret scripts + containing CR/LF instead of CR as + the end-of-line marker. Magic scripts must be executable + as is on the host, which for some hosts and + some shells will require filtering at the DOS end. + + Magic scripts are EXPERIMENTAL and + should NOT be relied upon. + + Default: None. Magic scripts disabled. + Example: magic script = user.csh + + diff --git a/docs/docbook/smbdotconf/misc/messagecommand.xml b/docs/docbook/smbdotconf/misc/messagecommand.xml new file mode 100644 index 0000000000..199fab5610 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/messagecommand.xml @@ -0,0 +1,65 @@ + + message command (G) + This specifies what command to run when the + server receives a WinPopup style message. + + This would normally be a command that would + deliver the message somehow. How this is to be done is + up to your imagination. + + An example is: + + message command = csh -c 'xedit %s;rm %s' & + + + This delivers the message using xedit, then + removes it afterwards. NOTE THAT IT IS VERY IMPORTANT + THAT THIS COMMAND RETURN IMMEDIATELY. That's why I + have the '&' on the end. If it doesn't return immediately then + your PCs may freeze when sending messages (they should recover + after 30 seconds, hopefully). + + All messages are delivered as the global guest user. + The command takes the standard substitutions, although + %u won't work (%U may be better + in this case). + + Apart from the standard substitutions, some additional + ones apply. In particular: + + + %s = the filename containing + the message. + + %t = the destination that + the message was sent to (probably the server name). + + %f = who the message + is from. + + + You could make this command send mail, or whatever else + takes your fancy. Please let us know of any really interesting + ideas you have. + + + Here's a way of sending the messages as mail to root: + + message command = /bin/mail -s 'message from %f on + %m' root < %s; rm %s + + If you don't have a message command then the message + won't be delivered and Samba will tell the sender there was + an error. Unfortunately WfWg totally ignores the error code + and carries on regardless, saying that the message was delivered. + + + If you want to silently delete it then try: + + message command = rm %s + + Default: no message command + Example: message command = csh -c 'xedit %s; + rm %s' & + + diff --git a/docs/docbook/smbdotconf/misc/nishomedir.xml b/docs/docbook/smbdotconf/misc/nishomedir.xml new file mode 100644 index 0000000000..5a2980d4fd --- /dev/null +++ b/docs/docbook/smbdotconf/misc/nishomedir.xml @@ -0,0 +1,30 @@ + + nis homedir (G) + Get the home share server from a NIS map. For + UNIX systems that use an automounter, the user's home directory + will often be mounted on a workstation on demand from a remote + server. + + When the Samba logon server is not the actual home directory + server, but is mounting the home directories via NFS then two + network hops would be required to access the users home directory + if the logon server told the client to use itself as the SMB server + for home directories (one over SMB and one over NFS). This can + be very slow. + + This option allows Samba to return the home share as + being on a different server to the logon server and as + long as a Samba daemon is running on the home directory server, + it will be mounted on the Samba client directly from the directory + server. When Samba is returning the home share to the client, it + will consult the NIS map specified in + homedir map and return the server + listed there. + + Note that for this option to work there must be a working + NIS system and the Samba server with this option must also + be a logon server. + + Default: nis homedir = no + + diff --git a/docs/docbook/smbdotconf/misc/panicaction.xml b/docs/docbook/smbdotconf/misc/panicaction.xml new file mode 100644 index 0000000000..6de37c2c17 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/panicaction.xml @@ -0,0 +1,12 @@ + + panic action (G) + This is a Samba developer option that allows a + system command to be called when either smbd + 8 or smbd + 8 crashes. This is usually used to + draw attention to the fact that a problem occurred. + + Default: panic action = <empty string> + Example: panic action = "/bin/sleep 90000" + + diff --git a/docs/docbook/smbdotconf/misc/piddirectory.xml b/docs/docbook/smbdotconf/misc/piddirectory.xml new file mode 100644 index 0000000000..81c1b13e75 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/piddirectory.xml @@ -0,0 +1,9 @@ + + pid directory (G) + This option specifies the directory where pid + files will be placed. + + Default: pid directory = ${prefix}/var/locks + Example: pid directory = /var/run/ + + diff --git a/docs/docbook/smbdotconf/misc/postexec.xml b/docs/docbook/smbdotconf/misc/postexec.xml new file mode 100644 index 0000000000..017177be3d --- /dev/null +++ b/docs/docbook/smbdotconf/misc/postexec.xml @@ -0,0 +1,22 @@ + + postexec (S) + This option specifies a command to be run + whenever the service is disconnected. It takes the usual + substitutions. The command may be run as the root on some + systems. + + An interesting example may be to unmount server + resources: + + postexec = /etc/umount /cdrom + + See also preexec + . + + Default: none (no command executed) + + + Example: postexec = echo \"%u disconnected from %S + from %m (%I)\" >> /tmp/log + + diff --git a/docs/docbook/smbdotconf/misc/preexec.xml b/docs/docbook/smbdotconf/misc/preexec.xml new file mode 100644 index 0000000000..fc047e008d --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preexec.xml @@ -0,0 +1,23 @@ + + preexec (S) + This option specifies a command to be run whenever + the service is connected to. It takes the usual substitutions. + + An interesting example is to send the users a welcome + message every time they log in. Maybe a message of the day? Here + is an example: + + preexec = csh -c 'echo \"Welcome to %S!\" | + /usr/local/samba/bin/smbclient -M %m -I %I' & + + Of course, this could get annoying after a while :-) + + See also preexec close + and postexec + . + + Default: none (no command executed) + Example: preexec = echo \"%u connected to %S from %m + (%I)\" >> /tmp/log + + diff --git a/docs/docbook/smbdotconf/misc/preexecclose.xml b/docs/docbook/smbdotconf/misc/preexecclose.xml new file mode 100644 index 0000000000..c617a7f7fa --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preexecclose.xml @@ -0,0 +1,9 @@ + + preexec close (S) + This boolean option controls whether a non-zero + return code from preexec + should close the service being connected to. + + Default: preexec close = no + + diff --git a/docs/docbook/smbdotconf/misc/preload.xml b/docs/docbook/smbdotconf/misc/preload.xml new file mode 100644 index 0000000000..574ed1a369 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/preload.xml @@ -0,0 +1,16 @@ + + preload (G) + This is a list of services that you want to be + automatically added to the browse lists. This is most useful + for homes and printers services that would otherwise not be + visible. + + Note that if you just want all printers in your + printcap file loaded then the + load printers option is easier. + + Default: no preloaded services + + Example: preload = fred lp colorlp + + diff --git a/docs/docbook/smbdotconf/misc/remoteannounce.xml b/docs/docbook/smbdotconf/misc/remoteannounce.xml new file mode 100644 index 0000000000..e6de4bdcaf --- /dev/null +++ b/docs/docbook/smbdotconf/misc/remoteannounce.xml @@ -0,0 +1,32 @@ + + remote announce (G) + This option allows you to setup nmbd(8) to periodically announce itself + to arbitrary IP addresses with an arbitrary workgroup name. + + This is useful if you want your Samba server to appear + in a remote workgroup for which the normal browse propagation + rules don't work. The remote workgroup can be anywhere that you + can send IP packets to. + + For example: + + remote announce = 192.168.2.255/SERVERS + 192.168.4.255/STAFF + + the above line would cause nmbd to announce itself + to the two given IP addresses using the given workgroup names. + If you leave out the workgroup name then the one given in + the workgroup + parameter is used instead. + + The IP addresses you choose would normally be the broadcast + addresses of the remote networks, but can also be the IP addresses + of known browse masters if your network config is that stable. + + See the documentation file BROWSING + in the docs/ directory. + + Default: remote announce = <empty string> + + + diff --git a/docs/docbook/smbdotconf/misc/remotebrowsesync.xml b/docs/docbook/smbdotconf/misc/remotebrowsesync.xml new file mode 100644 index 0000000000..8b0d863ed7 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/remotebrowsesync.xml @@ -0,0 +1,33 @@ + + remote browse sync (G) + This option allows you to setup nmbd(8) to periodically request + synchronization of browse lists with the master browser of a Samba + server that is on a remote segment. This option will allow you to + gain browse lists for multiple workgroups across routed networks. This + is done in a manner that does not work with any non-Samba servers. + + This is useful if you want your Samba server and all local + clients to appear in a remote workgroup for which the normal browse + propagation rules don't work. The remote workgroup can be anywhere + that you can send IP packets to. + + For example: + + remote browse sync = 192.168.2.255 192.168.4.255 + + + the above line would cause nmbd to request + the master browser on the specified subnets or addresses to + synchronize their browse lists with the local server. + + The IP addresses you choose would normally be the broadcast + addresses of the remote networks, but can also be the IP addresses + of known browse masters if your network config is that stable. If + a machine IP address is given Samba makes NO attempt to validate + that the remote machine is available, is listening, nor that it + is in fact the browse master on its segment. + + Default: remote browse sync = <empty string> + + + diff --git a/docs/docbook/smbdotconf/misc/rootpostexec.xml b/docs/docbook/smbdotconf/misc/rootpostexec.xml new file mode 100644 index 0000000000..ed60646677 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpostexec.xml @@ -0,0 +1,14 @@ + + root postexec (S) + This is the same as the postexec + parameter except that the command is run as root. This + is useful for unmounting filesystems + (such as CDROMs) after a connection is closed. + + See also + postexec. + + Default: root postexec = <empty string> + + + diff --git a/docs/docbook/smbdotconf/misc/rootpreexec.xml b/docs/docbook/smbdotconf/misc/rootpreexec.xml new file mode 100644 index 0000000000..29802b6d63 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpreexec.xml @@ -0,0 +1,15 @@ + + root preexec (S) + This is the same as the preexec + parameter except that the command is run as root. This + is useful for mounting filesystems (such as CDROMs) when a + connection is opened. + + See also + preexec and + preexec close. + + Default: root preexec = <empty string> + + + diff --git a/docs/docbook/smbdotconf/misc/rootpreexecclose.xml b/docs/docbook/smbdotconf/misc/rootpreexecclose.xml new file mode 100644 index 0000000000..d21b0dd7b5 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/rootpreexecclose.xml @@ -0,0 +1,12 @@ + + root preexec close (S) + This is the same as the preexec close + parameter except that the command is run as root. + + See also + preexec and + preexec close. + + Default: root preexec close = no + + diff --git a/docs/docbook/smbdotconf/misc/setdirectory.xml b/docs/docbook/smbdotconf/misc/setdirectory.xml new file mode 100644 index 0000000000..860632cdaf --- /dev/null +++ b/docs/docbook/smbdotconf/misc/setdirectory.xml @@ -0,0 +1,13 @@ + + set directory (S) + If set directory = no, then + users of the service may not use the setdir command to change + directory. + + The setdir command is only implemented + in the Digital Pathworks client. See the Pathworks documentation + for details. + + Default: set directory = no + + diff --git a/docs/docbook/smbdotconf/misc/socketaddress.xml b/docs/docbook/smbdotconf/misc/socketaddress.xml new file mode 100644 index 0000000000..e77737f18b --- /dev/null +++ b/docs/docbook/smbdotconf/misc/socketaddress.xml @@ -0,0 +1,14 @@ + + socket address (G) + This option allows you to control what + address Samba will listen for connections on. This is used to + support multiple virtual interfaces on the one server, each + with a different configuration. + + By default Samba will accept connections on any + address. + + Example: socket address = 192.168.2.20 + + + diff --git a/docs/docbook/smbdotconf/misc/sourceenvironment.xml b/docs/docbook/smbdotconf/misc/sourceenvironment.xml new file mode 100644 index 0000000000..07a8abce4d --- /dev/null +++ b/docs/docbook/smbdotconf/misc/sourceenvironment.xml @@ -0,0 +1,23 @@ + + source environment (G) + This parameter causes Samba to set environment + variables as per the content of the file named. + + If the value of this parameter starts with a "|" character + then Samba will treat that value as a pipe command to open and + will set the environment variables from the output of the pipe. + + The contents of the file or the output of the pipe should + be formatted as the output of the standard Unix env(1) + command. This is of the form : + Example environment entry: + SAMBA_NETBIOS_NAME = myhostname + + Default: No default value + Examples: source environment = |/etc/smb.conf.sh + + + Example: source environment = + /usr/local/smb_env_vars + + diff --git a/docs/docbook/smbdotconf/misc/timeoffset.xml b/docs/docbook/smbdotconf/misc/timeoffset.xml new file mode 100644 index 0000000000..0c973234c3 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/timeoffset.xml @@ -0,0 +1,11 @@ + + time offset (G) + This parameter is a setting in minutes to add + to the normal GMT to local time conversion. This is useful if + you are serving a lot of PCs that have incorrect daylight + saving time handling. + + Default: time offset = 0 + Example: time offset = 60 + + diff --git a/docs/docbook/smbdotconf/misc/utmp.xml b/docs/docbook/smbdotconf/misc/utmp.xml new file mode 100644 index 0000000000..014b85d6bc --- /dev/null +++ b/docs/docbook/smbdotconf/misc/utmp.xml @@ -0,0 +1,21 @@ + + utmp (G) + This boolean parameter is only available if + Samba has been configured and compiled with the option + --with-utmp. If set to yes then Samba will attempt + to add utmp or utmpx records (depending on the UNIX system) whenever a + connection is made to a Samba server. Sites may use this to record the + user connecting to a Samba share. + + Due to the requirements of the utmp record, we + are required to create a unique identifier for the + incoming user. Enabling this option creates an n^2 + algorithm to find this number. This may impede + performance on large installations. + + See also the + utmp directory parameter. + + Default: utmp = no + + diff --git a/docs/docbook/smbdotconf/misc/utmpdirectory.xml b/docs/docbook/smbdotconf/misc/utmpdirectory.xml new file mode 100644 index 0000000000..9e5574fb39 --- /dev/null +++ b/docs/docbook/smbdotconf/misc/utmpdirectory.xml @@ -0,0 +1,16 @@ + + utmp directory(G) + This parameter is only available if Samba has + been configured and compiled with the option + --with-utmp. It specifies a directory pathname that is + used to store the utmp or utmpx files (depending on the UNIX system) that + record user connections to a Samba server. See also the + utmp parameter. By default this is + not set, meaning the system will use whatever utmp file the + native system is set to use (usually + /var/run/utmp on Linux). + + Default: no utmp directory + Example: utmp directory = /var/run/utmp + + diff --git a/docs/docbook/smbdotconf/misc/volume.xml b/docs/docbook/smbdotconf/misc/volume.xml new file mode 100644 index 0000000000..f0a82c6f0c --- /dev/null +++ b/docs/docbook/smbdotconf/misc/volume.xml @@ -0,0 +1,9 @@ + + volume (S) + This allows you to override the volume label + returned for a share. Useful for CDROMs with installation programs + that insist on a particular volume label. + + Default: the name of the share + + diff --git a/docs/docbook/smbdotconf/misc/widelinks.xml b/docs/docbook/smbdotconf/misc/widelinks.xml new file mode 100644 index 0000000000..b3474ce26c --- /dev/null +++ b/docs/docbook/smbdotconf/misc/widelinks.xml @@ -0,0 +1,15 @@ + + wide links (S) + This parameter controls whether or not links + in the UNIX file system may be followed by the server. Links + that point to areas within the directory tree exported by the + server are always allowed; this parameter controls access only + to areas that are outside the directory tree being exported. + + Note that setting this parameter can have a negative + effect on your server performance due to the extra system calls + that Samba has to do in order to perform the link checks. + + Default: wide links = yes + + diff --git a/docs/docbook/smbdotconf/misc/wtmpdirectory.xml b/docs/docbook/smbdotconf/misc/wtmpdirectory.xml new file mode 100644 index 0000000000..bb144473ff --- /dev/null +++ b/docs/docbook/smbdotconf/misc/wtmpdirectory.xml @@ -0,0 +1,20 @@ + + wtmp directory(G) + This parameter is only available if Samba has + been configured and compiled with the option + --with-utmp. It specifies a directory pathname that is + used to store the wtmp or wtmpx files (depending on the UNIX system) that + record user connections to a Samba server. The difference with + the utmp directory is the fact that user info is kept after a user + has logged out. + + See also the + utmp parameter. By default this is + not set, meaning the system will use whatever utmp file the + native system is set to use (usually + /var/run/wtmp on Linux). + + Default: no wtmp directory + Example: wtmp directory = /var/log/wtmp + + diff --git a/docs/docbook/smbdotconf/printing/addprintercommand.xml b/docs/docbook/smbdotconf/printing/addprintercommand.xml new file mode 100644 index 0000000000..abff09cda4 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/addprintercommand.xml @@ -0,0 +1,60 @@ + + addprinter command (G) + With the introduction of MS-RPC based printing + support for Windows NT/2000 clients in Samba 2.2, The MS Add + Printer Wizard (APW) icon is now also available in the + "Printers..." folder displayed a share listing. The APW + allows for printers to be add remotely to a Samba or Windows + NT/2000 print server. + + For a Samba host this means that the printer must be + physically added to the underlying printing system. The add + printer command defines a script to be run which + will perform the necessary operations for adding the printer + to the print system and to add the appropriate service definition + to the smb.conf file in order that it can be + shared by smbd + 8. + + The addprinter command is + automatically invoked with the following parameter (in + order): + + + printer name + share name + port name + driver name + location + Windows 9x driver location + + + + All parameters are filled in from the PRINTER_INFO_2 structure sent + by the Windows NT/2000 client with one exception. The "Windows 9x + driver location" parameter is included for backwards compatibility + only. The remaining fields in the structure are generated from answers + to the APW questions. + + Once the addprinter command has + been executed, smbd will reparse the + smb.conf to determine if the share defined by the APW + exists. If the sharename is still invalid, then smbd + will return an ACCESS_DENIED error to the client. + + + The "add printer command" program can output a single line of text, + which Samba will set as the port the new printer is connected to. + If this line isn't output, Samba won't reload its printer shares. + + + See also + deleteprinter command, printing, + show add + printer wizard + + Default: none + Example: addprinter command = /usr/bin/addprinter + + + diff --git a/docs/docbook/smbdotconf/printing/defaultdevmode.xml b/docs/docbook/smbdotconf/printing/defaultdevmode.xml new file mode 100644 index 0000000000..9609038dcd --- /dev/null +++ b/docs/docbook/smbdotconf/printing/defaultdevmode.xml @@ -0,0 +1,34 @@ + + default devmode (S) + This parameter is only applicable to printable services. When smbd is serving + Printer Drivers to Windows NT/2k/XP clients, each printer on the Samba + server has a Device Mode which defines things such as paper size and + orientation and duplex settings. The device mode can only correctly be + generated by the printer driver itself (which can only be executed on a + Win32 platform). Because smbd is unable to execute the driver code + to generate the device mode, the default behavior is to set this field + to NULL. + + + Most problems with serving printer drivers to Windows NT/2k/XP clients + can be traced to a problem with the generated device mode. Certain drivers + will do things such as crashing the client's Explorer.exe with a NULL devmode. + However, other printer drivers can cause the client's spooler service + (spoolsv.exe) to die if the devmode was not created by the driver itself + (i.e. smbd generates a default devmode). + + + This parameter should be used with care and tested with the printer + driver in question. It is better to leave the device mode to NULL + and let the Windows client set the correct values. Because drivers do not + do this all the time, setting default devmode = yes + will instruct smbd to generate a default one. + + + For more information on Windows NT/2k printing and Device Modes, + see the MSDN documentation. + + + Default: default devmode = no + + diff --git a/docs/docbook/smbdotconf/printing/deleteprintercommand.xml b/docs/docbook/smbdotconf/printing/deleteprintercommand.xml new file mode 100644 index 0000000000..23f2ff76b0 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/deleteprintercommand.xml @@ -0,0 +1,35 @@ + + deleteprinter command (G) + With the introduction of MS-RPC based printer + support for Windows NT/2000 clients in Samba 2.2, it is now + possible to delete printer at run time by issuing the + DeletePrinter() RPC call. + + For a Samba host this means that the printer must be + physically deleted from underlying printing system. The + deleteprinter command defines a script to be run which + will perform the necessary operations for removing the printer + from the print system and from smb.conf. + + + The deleteprinter command is + automatically called with only one parameter: + "printer name". + + + Once the deleteprinter command has + been executed, smbd will reparse the + smb.conf to associated printer no longer exists. + If the sharename is still valid, then smbd + will return an ACCESS_DENIED error to the client. + + See also + addprinter command, printing, + show add + printer wizard + + Default: none + Example: deleteprinter command = /usr/bin/removeprinter + + + diff --git a/docs/docbook/smbdotconf/printing/disablespoolss.xml b/docs/docbook/smbdotconf/printing/disablespoolss.xml new file mode 100644 index 0000000000..dff1e63fab --- /dev/null +++ b/docs/docbook/smbdotconf/printing/disablespoolss.xml @@ -0,0 +1,20 @@ + + disable spoolss (G) + Enabling this parameter will disable Samba's support + for the SPOOLSS set of MS-RPC's and will yield identical behavior + as Samba 2.0.x. Windows NT/2000 clients will downgrade to using + Lanman style printing commands. Windows 9x/ME will be uneffected by + the parameter. However, this will also disable the ability to upload + printer drivers to a Samba server via the Windows NT Add Printer + Wizard or by using the NT printer properties dialog window. It will + also disable the capability of Windows NT/2000 clients to download + print drivers from the Samba host upon demand. + Be very careful about enabling this parameter. + + + See also use client driver + + + Default : disable spoolss = no + + diff --git a/docs/docbook/smbdotconf/printing/enumportscommand.xml b/docs/docbook/smbdotconf/printing/enumportscommand.xml new file mode 100644 index 0000000000..b1111a5e1c --- /dev/null +++ b/docs/docbook/smbdotconf/printing/enumportscommand.xml @@ -0,0 +1,22 @@ + + enumports command (G) + The concept of a "port" is fairly foreign + to UNIX hosts. Under Windows NT/2000 print servers, a port + is associated with a port monitor and generally takes the form of + a local port (i.e. LPT1:, COM1:, FILE:) or a remote port + (i.e. LPD Port Monitor, etc...). By default, Samba has only one + port defined--"Samba Printer Port". Under + Windows NT/2000, all printers must have a valid port name. + If you wish to have a list of ports displayed (smbd + does not use a port name for anything) other than + the default "Samba Printer Port", you + can define enumports command to point to + a program which should generate a list of ports, one per line, + to standard output. This listing will then be used in response + to the level 1 and 2 EnumPorts() RPC. + + Default: no enumports command + Example: enumports command = /usr/bin/listports + + + diff --git a/docs/docbook/smbdotconf/printing/loadprinters.xml b/docs/docbook/smbdotconf/printing/loadprinters.xml new file mode 100644 index 0000000000..adaa8afca9 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/loadprinters.xml @@ -0,0 +1,9 @@ + + load printers (G) + A boolean variable that controls whether all + printers in the printcap will be loaded for browsing by default. + See the printers section for + more details. + + Default: load printers = yes + diff --git a/docs/docbook/smbdotconf/printing/lppausecommand.xml b/docs/docbook/smbdotconf/printing/lppausecommand.xml new file mode 100644 index 0000000000..34d7c7f800 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lppausecommand.xml @@ -0,0 +1,41 @@ + + lppause command (S) + This parameter specifies the command to be + executed on the server host in order to stop printing or spooling + a specific print job. + + This command should be a program or script which takes + a printer name and job number to pause the print job. One way + of implementing this is by using job priorities, where jobs + having a too low priority won't be sent to the printer. + + If a %p is given then the printer name + is put in its place. A %j is replaced with + the job number (an integer). On HPUX (see printing=hpux + ), if the -p%p option is added + to the lpq command, the job will show up with the correct status, i.e. + if the job priority is lower than the set fence priority it will + have the PAUSED status, whereas if the priority is equal or higher it + will have the SPOOLED or PRINTING status. + + Note that it is good practice to include the absolute path + in the lppause command as the PATH may not be available to the server. + + See also the printing + parameter. + + Default: Currently no default value is given to + this string, unless the value of the printing + parameter is SYSV, in which case the default is : + + lp -i %p-%j -H hold + + or if the value of the printing parameter + is SOFTQ, then the default is: + + qstat -s -j%j -h + + Example for HPUX: lppause command = /usr/bin/lpalt + %p-%j -p0 + + diff --git a/docs/docbook/smbdotconf/printing/lpqcachetime.xml b/docs/docbook/smbdotconf/printing/lpqcachetime.xml new file mode 100644 index 0000000000..6f351fdaf9 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lpqcachetime.xml @@ -0,0 +1,26 @@ + + lpq cache time (G) + This controls how long lpq info will be cached + for to prevent the lpq command being called too + often. A separate cache is kept for each variation of the + lpq command used by the system, so if you use different + lpq commands for different users then they won't + share cache information. + + The cache files are stored in /tmp/lpq.xxxx + where xxxx is a hash of the lpq command in use. + + The default is 10 seconds, meaning that the cached results + of a previous identical lpq command will be used + if the cached data is less than 10 seconds old. A large value may + be advisable if your lpq command is very slow. + + A value of 0 will disable caching completely. + + See also the printing + parameter. + + Default: lpq cache time = 10 + Example: lpq cache time = 30 + + diff --git a/docs/docbook/smbdotconf/printing/lpqcommand.xml b/docs/docbook/smbdotconf/printing/lpqcommand.xml new file mode 100644 index 0000000000..ddcdf1ef49 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lpqcommand.xml @@ -0,0 +1,41 @@ + + lpq command (S) + This parameter specifies the command to be + executed on the server host in order to obtain lpq + -style printer status information. + + This command should be a program or script which + takes a printer name as its only parameter and outputs printer + status information. + + Currently nine styles of printer status information + are supported; BSD, AIX, LPRNG, PLP, SYSV, HPUX, QNX, CUPS, and SOFTQ. + This covers most UNIX systems. You control which type is expected + using the printing = option. + + Some clients (notably Windows for Workgroups) may not + correctly send the connection number for the printer they are + requesting status information about. To get around this, the + server reports on the first printer service connected to by the + client. This only happens if the connection number sent is invalid. + + If a %p is given then the printer name + is put in its place. Otherwise it is placed at the end of the + command. + + Note that it is good practice to include the absolute path + in the lpq command as the $PATH + may not be available to the server. When compiled with + the CUPS libraries, no lpq command is + needed because smbd will make a library call to obtain the + print queue listing. + + See also the printing + parameter. + + Default: depends on the setting of + printing + + Example: lpq command = /usr/bin/lpq -P%p + + diff --git a/docs/docbook/smbdotconf/printing/lpresumecommand.xml b/docs/docbook/smbdotconf/printing/lpresumecommand.xml new file mode 100644 index 0000000000..fbb1ac71ad --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lpresumecommand.xml @@ -0,0 +1,37 @@ + + lpresume command (S) + This parameter specifies the command to be + executed on the server host in order to restart or continue + printing or spooling a specific print job. + + This command should be a program or script which takes + a printer name and job number to resume the print job. See + also the lppause command + parameter. + + If a %p is given then the printer name + is put in its place. A %j is replaced with + the job number (an integer). + + Note that it is good practice to include the absolute path + in the lpresume command as the PATH may not + be available to the server. + + See also the printing + parameter. + + Default: Currently no default value is given + to this string, unless the value of the printing + parameter is SYSV, in which case the default is : + + lp -i %p-%j -H resume + + or if the value of the printing parameter + is SOFTQ, then the default is: + + qstat -s -j%j -r + + Example for HPUX: lpresume command = /usr/bin/lpalt + %p-%j -p2 + + diff --git a/docs/docbook/smbdotconf/printing/lprmcommand.xml b/docs/docbook/smbdotconf/printing/lprmcommand.xml new file mode 100644 index 0000000000..7f59d6c5a0 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/lprmcommand.xml @@ -0,0 +1,27 @@ + + lprm command (S) + This parameter specifies the command to be + executed on the server host in order to delete a print job. + + This command should be a program or script which takes + a printer name and job number, and deletes the print job. + + If a %p is given then the printer name + is put in its place. A %j is replaced with + the job number (an integer). + + Note that it is good practice to include the absolute + path in the lprm command as the PATH may not be + available to the server. + + See also the printing + parameter. + + Default: depends on the setting of printing + + + Example 1: lprm command = /usr/bin/lprm -P%p %j + + Example 2: lprm command = /usr/bin/cancel %p-%j + + diff --git a/docs/docbook/smbdotconf/printing/maxprintjobs.xml b/docs/docbook/smbdotconf/printing/maxprintjobs.xml new file mode 100644 index 0000000000..f0c7d83d3f --- /dev/null +++ b/docs/docbook/smbdotconf/printing/maxprintjobs.xml @@ -0,0 +1,14 @@ + + max print jobs (S) + This parameter limits the maximum number of + jobs allowable in a Samba printer queue at any given moment. + If this number is exceeded, smbd + 8 will remote "Out of Space" to the client. + See all total + print jobs. + + + Default: max print jobs = 1000 + Example: max print jobs = 5000 + + diff --git a/docs/docbook/smbdotconf/printing/os2drivermap.xml b/docs/docbook/smbdotconf/printing/os2drivermap.xml new file mode 100644 index 0000000000..fdfba35a49 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/os2drivermap.xml @@ -0,0 +1,22 @@ + + os2 driver map (G) + The parameter is used to define the absolute + path to a file containing a mapping of Windows NT printer driver + names to OS/2 printer driver names. The format is: + + <nt driver name> = <os2 driver + name>.<device name> + + For example, a valid entry using the HP LaserJet 5 + printer driver would appear as HP LaserJet 5L = LASERJET.HP + LaserJet 5L. + + The need for the file is due to the printer driver namespace + problem described in the Samba + Printing HOWTO. For more details on OS/2 clients, please + refer to the OS2-Client-HOWTO containing in the Samba documentation. + + Default: os2 driver map = <empty string> + + + diff --git a/docs/docbook/smbdotconf/printing/printable.xml b/docs/docbook/smbdotconf/printing/printable.xml new file mode 100644 index 0000000000..22d4d73b01 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printable.xml @@ -0,0 +1,15 @@ + + printable (S) + If this parameter is yes, then + clients may open, write to and submit spool files on the directory + specified for the service. + + Note that a printable service will ALWAYS allow writing + to the service path (user privileges permitting) via the spooling + of print data. The read only + parameter controls only non-printing access to + the resource. + + Default: printable = no + + diff --git a/docs/docbook/smbdotconf/printing/printcap.xml b/docs/docbook/smbdotconf/printing/printcap.xml new file mode 100644 index 0000000000..2f5e4af580 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printcap.xml @@ -0,0 +1,6 @@ + + printcap (G) + Synonym for + printcap name. + + diff --git a/docs/docbook/smbdotconf/printing/printcapname.xml b/docs/docbook/smbdotconf/printing/printcapname.xml new file mode 100644 index 0000000000..fcfeada54c --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printcapname.xml @@ -0,0 +1,47 @@ + + printcap name (G) + This parameter may be used to override the + compiled-in default printcap name used by the server (usually + /etc/printcap). See the discussion of the [printers] section above for reasons + why you might want to do this. + + To use the CUPS printing interface set printcap name = cups + . This should be supplemented by an addtional setting + printing = cups in the [global] + section. printcap name = cups will use the + "dummy" printcap created by CUPS, as specified in your CUPS + configuration file. + + + On System V systems that use lpstat to + list available printers you can use printcap name = lpstat + to automatically obtain lists of available printers. This + is the default for systems that define SYSV at configure time in + Samba (this includes most System V based systems). If + printcap name is set to lpstat on + these systems then Samba will launch lpstat -v and + attempt to parse the output to obtain a printer list. + + A minimal printcap file would look something like this: + + +print1|My Printer 1 +print2|My Printer 2 +print3|My Printer 3 +print4|My Printer 4 +print5|My Printer 5 + + + where the '|' separates aliases of a printer. The fact + that the second alias has a space in it gives a hint to Samba + that it's a comment. + + NOTE: Under AIX the default printcap + name is /etc/qconfig. Samba will assume the + file is in AIX qconfig format if the string + qconfig appears in the printcap filename. + + Default: printcap name = /etc/printcap + Example: printcap name = /etc/myprintcap + + diff --git a/docs/docbook/smbdotconf/printing/printcommand.xml b/docs/docbook/smbdotconf/printing/printcommand.xml new file mode 100644 index 0000000000..c996ed6c2e --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printcommand.xml @@ -0,0 +1,86 @@ + + print command (S) + After a print job has finished spooling to + a service, this command will be used via a system() + call to process the spool file. Typically the command specified will + submit the spool file to the host's printing subsystem, but there + is no requirement that this be the case. The server will not remove + the spool file, so whatever command you specify should remove the + spool file when it has been processed, otherwise you will need to + manually remove old spool files. + + The print command is simply a text string. It will be used + verbatim after macro substitutions have been made: + + s, %p - the path to the spool + file name + + %p - the appropriate printer + name + + %J - the job + name as transmitted by the client. + + %c - The number of printed pages + of the spooled job (if known). + + %z - the size of the spooled + print job (in bytes) + + The print command MUST contain at least + one occurrence of %s or %f + - the %p is optional. At the time + a job is submitted, if no printer name is supplied the %p + will be silently removed from the printer command. + + If specified in the [global] section, the print command given + will be used for any printable service that does not have its own + print command specified. + + If there is neither a specified print command for a + printable service nor a global print command, spool files will + be created but not processed and (most importantly) not removed. + + Note that printing may fail on some UNIXes from the + nobody account. If this happens then create + an alternative guest account that can print and set the guest account + in the [global] section. + + You can form quite complex print commands by realizing + that they are just passed to a shell. For example the following + will log a print job, print the file, then remove it. Note that + ';' is the usual separator for command in shell scripts. + + print command = echo Printing %s >> + /tmp/print.log; lpr -P %p %s; rm %s + + You may have to vary this command considerably depending + on how you normally print files on your system. The default for + the parameter varies depending on the setting of the + printing parameter. + + Default: For printing = BSD, AIX, QNX, LPRNG + or PLP : + print command = lpr -r -P%p %s + + For printing = SYSV or HPUX : + print command = lp -c -d%p %s; rm %s + + For printing = SOFTQ : + print command = lp -d%p -s %s; rm %s + + For printing = CUPS : If SAMBA is compiled against + libcups, then printcap = cups + uses the CUPS API to + submit jobs, etc. Otherwise it maps to the System V + commands with the -oraw option for printing, i.e. it + uses lp -c -d%p -oraw; rm %s. + With printing = cups, + and if SAMBA is compiled against libcups, any manually + set print command will be ignored. + + + Example: print command = /usr/local/samba/bin/myprintscript + %p %s + + diff --git a/docs/docbook/smbdotconf/printing/printer.xml b/docs/docbook/smbdotconf/printing/printer.xml new file mode 100644 index 0000000000..4cf90b06fa --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printer.xml @@ -0,0 +1,6 @@ + + printer (S) + Synonym for + printer name. + + diff --git a/docs/docbook/smbdotconf/printing/printername.xml b/docs/docbook/smbdotconf/printing/printername.xml new file mode 100644 index 0000000000..25e6afa1f2 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printername.xml @@ -0,0 +1,15 @@ + + printer name (S) + This parameter specifies the name of the printer + to which print jobs spooled through a printable service will be sent. + + If specified in the [global] section, the printer + name given will be used for any printable service that does + not have its own printer name specified. + + Default: none (but may be lp + on many systems) + + Example: printer name = laserwriter + + diff --git a/docs/docbook/smbdotconf/printing/printing.xml b/docs/docbook/smbdotconf/printing/printing.xml new file mode 100644 index 0000000000..d49c0e2471 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printing.xml @@ -0,0 +1,26 @@ + + printing (S) + This parameters controls how printer status + information is interpreted on your system. It also affects the + default values for the print command, + lpq command, lppause command + , lpresume command, and + lprm command if specified in the + [global] section. + + Currently nine printing styles are supported. They are + BSD, AIX, + LPRNG, PLP, + SYSV, HPUX, + QNX, SOFTQ, + and CUPS. + + To see what the defaults are for the other print + commands when using the various options use the testparm(1) program. + + This option can be set on a per printer basis + + See also the discussion in the + [printers] section. + + diff --git a/docs/docbook/smbdotconf/printing/printok.xml b/docs/docbook/smbdotconf/printing/printok.xml new file mode 100644 index 0000000000..7900e91bbb --- /dev/null +++ b/docs/docbook/smbdotconf/printing/printok.xml @@ -0,0 +1,6 @@ + + print ok (S) + Synonym for + printable. + + diff --git a/docs/docbook/smbdotconf/printing/queuepausecommand.xml b/docs/docbook/smbdotconf/printing/queuepausecommand.xml new file mode 100644 index 0000000000..c991994f7f --- /dev/null +++ b/docs/docbook/smbdotconf/printing/queuepausecommand.xml @@ -0,0 +1,26 @@ + + queuepause command (S) + This parameter specifies the command to be + executed on the server host in order to pause the printer queue. + + This command should be a program or script which takes + a printer name as its only parameter and stops the printer queue, + such that no longer jobs are submitted to the printer. + + This command is not supported by Windows for Workgroups, + but can be issued from the Printers window under Windows 95 + and NT. + + If a %p is given then the printer name + is put in its place. Otherwise it is placed at the end of the command. + + + Note that it is good practice to include the absolute + path in the command as the PATH may not be available to the + server. + + Default: depends on the setting of printing + + Example: queuepause command = disable %p + + diff --git a/docs/docbook/smbdotconf/printing/queueresumecommand.xml b/docs/docbook/smbdotconf/printing/queueresumecommand.xml new file mode 100644 index 0000000000..7c0d60961a --- /dev/null +++ b/docs/docbook/smbdotconf/printing/queueresumecommand.xml @@ -0,0 +1,31 @@ + + queueresume command (S) + This parameter specifies the command to be + executed on the server host in order to resume the printer queue. It + is the command to undo the behavior that is caused by the + previous parameter ( + queuepause command). + + This command should be a program or script which takes + a printer name as its only parameter and resumes the printer queue, + such that queued jobs are resubmitted to the printer. + + This command is not supported by Windows for Workgroups, + but can be issued from the Printers window under Windows 95 + and NT. + + If a %p is given then the printer name + is put in its place. Otherwise it is placed at the end of the + command. + + Note that it is good practice to include the absolute + path in the command as the PATH may not be available to the + server. + + Default: depends on the setting of printing + + + Example: queuepause command = enable %p + + + diff --git a/docs/docbook/smbdotconf/printing/showaddprinterwizard.xml b/docs/docbook/smbdotconf/printing/showaddprinterwizard.xml new file mode 100644 index 0000000000..9bf5160ad5 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/showaddprinterwizard.xml @@ -0,0 +1,31 @@ + + show add printer wizard (G) + With the introduction of MS-RPC based printing support + for Windows NT/2000 client in Samba 2.2, a "Printers..." folder will + appear on Samba hosts in the share listing. Normally this folder will + contain an icon for the MS Add Printer Wizard (APW). However, it is + possible to disable this feature regardless of the level of privilege + of the connected user. + + Under normal circumstances, the Windows NT/2000 client will + open a handle on the printer server with OpenPrinterEx() asking for + Administrator privileges. If the user does not have administrative + access on the print server (i.e is not root or a member of the + printer admin group), the OpenPrinterEx() + call fails and the client makes another open call with a request for + a lower privilege level. This should succeed, however the APW + icon will not be displayed. + + Disabling the show add printer wizard + parameter will always cause the OpenPrinterEx() on the server + to fail. Thus the APW icon will never be displayed. + Note :This does not prevent the same user from having + administrative privilege on an individual printer. + + See also addprinter + command, + deleteprinter command, printer admin + + Default :show add printer wizard = yes + + diff --git a/docs/docbook/smbdotconf/printing/totalprintjobs.xml b/docs/docbook/smbdotconf/printing/totalprintjobs.xml new file mode 100644 index 0000000000..25784a3c29 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/totalprintjobs.xml @@ -0,0 +1,18 @@ + + total print jobs (G) + This parameter accepts an integer value which defines + a limit on the maximum number of print jobs that will be accepted + system wide at any given time. If a print job is submitted + by a client which will exceed this number, then smbd + 8 will return an + error indicating that no space is available on the server. The + default value of 0 means that no such limit exists. This parameter + can be used to prevent a server from exceeding its capacity and is + designed as a printing throttle. See also + max print jobs. + + + Default: total print jobs = 0 + Example: total print jobs = 5000 + + diff --git a/docs/docbook/smbdotconf/printing/useclientdriver.xml b/docs/docbook/smbdotconf/printing/useclientdriver.xml new file mode 100644 index 0000000000..8327d0aaa4 --- /dev/null +++ b/docs/docbook/smbdotconf/printing/useclientdriver.xml @@ -0,0 +1,35 @@ + + use client driver (S) + This parameter applies only to Windows NT/2000 + clients. It has no affect on Windows 95/98/ME clients. When + serving a printer to Windows NT/2000 clients without first installing + a valid printer driver on the Samba host, the client will be required + to install a local printer driver. From this point on, the client + will treat the print as a local printer and not a network printer + connection. This is much the same behavior that will occur + when disable spoolss = yes. + + The differentiating + factor is that under normal circumstances, the NT/2000 client will + attempt to open the network printer using MS-RPC. The problem is that + because the client considers the printer to be local, it will attempt + to issue the OpenPrinterEx() call requesting access rights associated + with the logged on user. If the user possesses local administator rights + but not root privilegde on the Samba host (often the case), the OpenPrinterEx() + call will fail. The result is that the client will now display an "Access + Denied; Unable to connect" message in the printer queue window (even though + jobs may successfully be printed). + + If this parameter is enabled for a printer, then any attempt + to open the printer with the PRINTER_ACCESS_ADMINISTER right is mapped + to PRINTER_ACCESS_USE instead. Thus allowing the OpenPrinterEx() + call to succeed. This parameter MUST not be able enabled + on a print share which has valid print driver installed on the Samba + server. + + See also disable spoolss + + + Default: use client driver = no + + diff --git a/docs/docbook/smbdotconf/process-all.sh b/docs/docbook/smbdotconf/process-all.sh new file mode 100755 index 0000000000..6d8c9941b4 --- /dev/null +++ b/docs/docbook/smbdotconf/process-all.sh @@ -0,0 +1,15 @@ +#!/bin/sh +sh generate-file-list.sh >parameters.all.xml + +xsltproc --xinclude \ + --param smb.context "'G'" \ + --output parameters.global.xml \ + generate-context.xsl parameters.all.xml + +xsltproc --xinclude \ + --param smb.context "'S'" \ + --output parameters.service.xml \ + generate-context.xsl parameters.all.xml + +xsltproc --xinclude expand-smb.conf.xsl smb.conf.5.xml | \ +xsltproc http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl - diff --git a/docs/docbook/smbdotconf/protocol/announceas.xml b/docs/docbook/smbdotconf/protocol/announceas.xml new file mode 100644 index 0000000000..1f3169609c --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/announceas.xml @@ -0,0 +1,18 @@ + + announce as (G) + This specifies what type of server nmbd + 8 will announce itself as, to a network neighborhood browse + list. By default this is set to Windows NT. The valid options + are : "NT Server" (which can also be written as "NT"), + "NT Workstation", "Win95" or "WfW" meaning Windows NT Server, + Windows NT Workstation, Windows 95 and Windows for Workgroups + respectively. Do not change this parameter unless you have a + specific need to stop Samba appearing as an NT server as this + may prevent Samba servers from participating as browser servers + correctly. + + Default: announce as = NT Server + + Example: announce as = Win95 + + diff --git a/docs/docbook/smbdotconf/protocol/announceversion.xml b/docs/docbook/smbdotconf/protocol/announceversion.xml new file mode 100644 index 0000000000..03ad429dbd --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/announceversion.xml @@ -0,0 +1,12 @@ + + announce version (G) + This specifies the major and minor version numbers + that nmbd will use when announcing itself as a server. The default + is 4.9. Do not change this parameter unless you have a specific + need to set a Samba server to be a downlevel server. + + Default: announce version = 4.9 + + Example: announce version = 2.0 + + diff --git a/docs/docbook/smbdotconf/protocol/disablenetbios.xml b/docs/docbook/smbdotconf/protocol/disablenetbios.xml new file mode 100644 index 0000000000..ac97cdf7c3 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/disablenetbios.xml @@ -0,0 +1,14 @@ + + disable netbios (G) + Enabling this parameter will disable netbios support + in Samba. Netbios is the only available form of browsing in + all windows versions except for 2000 and XP. + + Note that clients that only support netbios won't be able to + see your samba server when netbios support is disabled. + + + Default: disable netbios = no + Example: disable netbios = yes + + diff --git a/docs/docbook/smbdotconf/protocol/largereadwrite.xml b/docs/docbook/smbdotconf/protocol/largereadwrite.xml new file mode 100644 index 0000000000..9aa28593e6 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/largereadwrite.xml @@ -0,0 +1,15 @@ + + large readwrite (G) + This parameter determines whether or not smbd + 8 supports the new 64k streaming + read and write varient SMB requests introduced + with Windows 2000. Note that due to Windows 2000 client redirector bugs + this requires Samba to be running on a 64-bit capable operating system such + as IRIX, Solaris or a Linux 2.4 kernel. Can improve performance by 10% with + Windows 2000 clients. Defaults to on. Not as tested as some other Samba + code paths. + + + Default : large readwrite = yes + + diff --git a/docs/docbook/smbdotconf/protocol/maxmux.xml b/docs/docbook/smbdotconf/protocol/maxmux.xml new file mode 100644 index 0000000000..51296e0747 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/maxmux.xml @@ -0,0 +1,9 @@ + + max mux (G) + This option controls the maximum number of + outstanding simultaneous SMB operations that Samba tells the client + it will allow. You should never need to set this parameter. + + Default: max mux = 50 + + diff --git a/docs/docbook/smbdotconf/protocol/maxprotocol.xml b/docs/docbook/smbdotconf/protocol/maxprotocol.xml new file mode 100644 index 0000000000..be859f8ee3 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/maxprotocol.xml @@ -0,0 +1,35 @@ + + max protocol (G) + The value of the parameter (a string) is the highest + protocol level that will be supported by the server. + + Possible values are : + + CORE: Earliest version. No + concept of user names. + + COREPLUS: Slight improvements on + CORE for efficiency. + + LANMAN1: First + modern version of the protocol. Long filename + support. + + LANMAN2: Updates to Lanman1 protocol. + + + NT1: Current up to date version of + the protocol. Used by Windows NT. Known as CIFS. + + + Normally this option should not be set as the automatic + negotiation phase in the SMB protocol takes care of choosing + the appropriate protocol. + + See also min + protocol + + Default: max protocol = NT1 + Example: max protocol = LANMAN1 + + diff --git a/docs/docbook/smbdotconf/protocol/maxttl.xml b/docs/docbook/smbdotconf/protocol/maxttl.xml new file mode 100644 index 0000000000..04c6771308 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/maxttl.xml @@ -0,0 +1,12 @@ + + max ttl (G) + This option tells nmbd + 8 + what the default 'time to live' of NetBIOS names should be (in seconds) + when nmbd is requesting a name using either a + broadcast packet or from a WINS server. You should never need to + change this parameter. The default is 3 days. + + Default: max ttl = 259200 + + diff --git a/docs/docbook/smbdotconf/protocol/maxwinsttl.xml b/docs/docbook/smbdotconf/protocol/maxwinsttl.xml new file mode 100644 index 0000000000..c8e2d9df8d --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/maxwinsttl.xml @@ -0,0 +1,15 @@ + + max wins ttl (G) + This option tells smbd + 8 when acting as a WINS server ( + wins support = yes) what the maximum + 'time to live' of NetBIOS names that nmbd + will grant will be (in seconds). You should never need to change this + parameter. The default is 6 days (518400 seconds). + + See also the min + wins ttl parameter. + + Default: max wins ttl = 518400 + + diff --git a/docs/docbook/smbdotconf/protocol/maxxmit.xml b/docs/docbook/smbdotconf/protocol/maxxmit.xml new file mode 100644 index 0000000000..c16cf47655 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/maxxmit.xml @@ -0,0 +1,12 @@ + + max xmit (G) + This option controls the maximum packet size + that will be negotiated by Samba. The default is 65535, which + is the maximum. In some cases you may find you get better performance + with a smaller value. A value below 2048 is likely to cause problems. + + + Default: max xmit = 65535 + Example: max xmit = 8192 + + diff --git a/docs/docbook/smbdotconf/protocol/minprotocol.xml b/docs/docbook/smbdotconf/protocol/minprotocol.xml new file mode 100644 index 0000000000..6b1d420a4b --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/minprotocol.xml @@ -0,0 +1,20 @@ + + min protocol (G) + The value of the parameter (a string) is the + lowest SMB protocol dialect than Samba will support. Please refer + to the max protocol + parameter for a list of valid protocol names and a brief description + of each. You may also wish to refer to the C source code in + source/smbd/negprot.c for a listing of known protocol + dialects supported by clients. + + If you are viewing this parameter as a security measure, you should + also refer to the lanman + auth parameter. Otherwise, you should never need + to change this parameter. + + Default : min protocol = CORE + Example : min protocol = NT1 # disable DOS + clients + + diff --git a/docs/docbook/smbdotconf/protocol/minwinsttl.xml b/docs/docbook/smbdotconf/protocol/minwinsttl.xml new file mode 100644 index 0000000000..e67c253f2e --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/minwinsttl.xml @@ -0,0 +1,13 @@ + + min wins ttl (G) + This option tells nmbd + 8 + when acting as a WINS server ( + wins support = yes) what the minimum 'time to live' + of NetBIOS names that nmbd will grant will be (in + seconds). You should never need to change this parameter. The default + is 6 hours (21600 seconds). + + Default: min wins ttl = 21600 + + diff --git a/docs/docbook/smbdotconf/protocol/nameresolveorder.xml b/docs/docbook/smbdotconf/protocol/nameresolveorder.xml new file mode 100644 index 0000000000..a5dd893902 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/nameresolveorder.xml @@ -0,0 +1,47 @@ + + name resolve order (G) + This option is used by the programs in the Samba + suite to determine what naming services to use and in what order + to resolve host names to IP addresses. The option takes a space + separated string of name resolution options. + + The options are :"lmhosts", "host", "wins" and "bcast". They + cause names to be resolved as follows : + + + lmhosts : Lookup an IP + address in the Samba lmhosts file. If the line in lmhosts has + no name type attached to the NetBIOS name (see the lmhosts(5) for details) then + any name type matches for lookup. + + host : Do a standard host + name to IP address resolution, using the system /etc/hosts + , NIS, or DNS lookups. This method of name resolution + is operating system depended for instance on IRIX or Solaris this + may be controlled by the /etc/nsswitch.conf + file. Note that this method is only used if the NetBIOS name + type being queried is the 0x20 (server) name type, otherwise + it is ignored. + + wins : Query a name with + the IP address listed in the + wins server parameter. If no WINS server has + been specified this method will be ignored. + + bcast : Do a broadcast on + each of the known local interfaces listed in the interfaces + parameter. This is the least reliable of the name resolution + methods as it depends on the target host being on a locally + connected subnet. + + + Default: name resolve order = lmhosts host wins bcast + + Example: name resolve order = lmhosts bcast host + + + This will cause the local lmhosts file to be examined + first, followed by a broadcast attempt, followed by a normal + system hostname lookup. + + diff --git a/docs/docbook/smbdotconf/protocol/ntaclsupport.xml b/docs/docbook/smbdotconf/protocol/ntaclsupport.xml new file mode 100644 index 0000000000..df0d8dc068 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/ntaclsupport.xml @@ -0,0 +1,11 @@ + + nt acl support (S) + This boolean parameter controls whether + smbd(8) will attempt to map + UNIX permissions into Windows NT access control lists. + This parameter was formally a global parameter in releases + prior to 2.2.2. + + Default: nt acl support = yes + + diff --git a/docs/docbook/smbdotconf/protocol/ntpipesupport.xml b/docs/docbook/smbdotconf/protocol/ntpipesupport.xml new file mode 100644 index 0000000000..cab2032847 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/ntpipesupport.xml @@ -0,0 +1,12 @@ + + nt pipe support (G) + This boolean parameter controls whether + smbd + 8 will allow Windows NT + clients to connect to the NT SMB specific IPC$ + pipes. This is a developer debugging option and can be left + alone. + + Default: nt pipe support = yes + + diff --git a/docs/docbook/smbdotconf/protocol/ntstatussupport.xml b/docs/docbook/smbdotconf/protocol/ntstatussupport.xml new file mode 100644 index 0000000000..17dafa47c5 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/ntstatussupport.xml @@ -0,0 +1,14 @@ + + nt status support (G) + This boolean parameter controls whether smbd(8) will negotiate NT specific status + support with Windows NT/2k/XP clients. This is a developer + debugging option and should be left alone. + If this option is set to no then Samba offers + exactly the same DOS error codes that versions prior to Samba 2.2.3 + reported. + + You should not need to ever disable this parameter. + + Default: nt status support = yes + + diff --git a/docs/docbook/smbdotconf/protocol/protocol.xml b/docs/docbook/smbdotconf/protocol/protocol.xml new file mode 100644 index 0000000000..5161806cfc --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/protocol.xml @@ -0,0 +1,5 @@ + + protocol (G) + Synonym for + max protocol. + diff --git a/docs/docbook/smbdotconf/protocol/readbmpx.xml b/docs/docbook/smbdotconf/protocol/readbmpx.xml new file mode 100644 index 0000000000..0bc8f1d10b --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/readbmpx.xml @@ -0,0 +1,10 @@ + + read bmpx (G) + This boolean parameter controls whether smbd(8) will support the "Read + Block Multiplex" SMB. This is now rarely used and defaults to + no. You should never need to set this + parameter. + + Default: read bmpx = no + + diff --git a/docs/docbook/smbdotconf/protocol/readraw.xml b/docs/docbook/smbdotconf/protocol/readraw.xml new file mode 100644 index 0000000000..b867816e84 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/readraw.xml @@ -0,0 +1,21 @@ + + read raw (G) + This parameter controls whether or not the server + will support the raw read SMB requests when transferring data + to clients. + + If enabled, raw reads allow reads of 65535 bytes in + one packet. This typically provides a major performance benefit. + + + However, some clients either negotiate the allowable + block size incorrectly or are incapable of supporting larger block + sizes, and for these clients you may need to disable raw reads. + + In general this parameter should be viewed as a system tuning + tool and left severely alone. See also + write raw. + + Default: read raw = yes + + diff --git a/docs/docbook/smbdotconf/protocol/smbports.xml b/docs/docbook/smbdotconf/protocol/smbports.xml new file mode 100644 index 0000000000..ed088ab9d2 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/smbports.xml @@ -0,0 +1,10 @@ + + smb ports (G) + Specifies which ports the server should listen on + for SMB traffic. + + + Default: smb ports = 445 139 + + + diff --git a/docs/docbook/smbdotconf/protocol/timeserver.xml b/docs/docbook/smbdotconf/protocol/timeserver.xml new file mode 100644 index 0000000000..eb1a720a8d --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/timeserver.xml @@ -0,0 +1,9 @@ + + time server (G) + This parameter determines if nmbd + 8 advertises itself as a time server to Windows + clients. + + Default: time server = no + + diff --git a/docs/docbook/smbdotconf/protocol/unicode.xml b/docs/docbook/smbdotconf/protocol/unicode.xml new file mode 100644 index 0000000000..866dad28a0 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/unicode.xml @@ -0,0 +1,11 @@ + + unicode (G) + Specifies whether Samba should try + to use unicode on the wire by default. Note: This does NOT + mean that samba will assume that the unix machine uses unicode! + + + Default: unicode = yes + + + diff --git a/docs/docbook/smbdotconf/protocol/unixextensions.xml b/docs/docbook/smbdotconf/protocol/unixextensions.xml new file mode 100644 index 0000000000..d0adde9d27 --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/unixextensions.xml @@ -0,0 +1,12 @@ + + unix extensions(G) + This boolean parameter controls whether Samba + implments the CIFS UNIX extensions, as defined by HP. + These extensions enable Samba to better serve UNIX CIFS clients + by supporting features such as symbolic links, hard links, etc... + These extensions require a similarly enabled client, and are of + no current use to Windows clients. + + Default: unix extensions = no + + diff --git a/docs/docbook/smbdotconf/protocol/usespnego.xml b/docs/docbook/smbdotconf/protocol/usespnego.xml new file mode 100644 index 0000000000..9e3c873a4b --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/usespnego.xml @@ -0,0 +1,11 @@ + + use spnego (G) + This variable controls controls whether samba will try + to use Simple and Protected NEGOciation (as specified by rfc2478) with + WindowsXP and Windows2000sp2 clients to agree upon an authentication mechanism. + Unless further issues are discovered with our SPNEGO + implementation, there is no reason this should ever be + disabled. + Default: use spnego = yes + + diff --git a/docs/docbook/smbdotconf/protocol/writeraw.xml b/docs/docbook/smbdotconf/protocol/writeraw.xml new file mode 100644 index 0000000000..dbaad0130e --- /dev/null +++ b/docs/docbook/smbdotconf/protocol/writeraw.xml @@ -0,0 +1,9 @@ + + write raw (G) + This parameter controls whether or not the server + will support raw write SMB's when transferring data from clients. + You should never need to change this parameter. + + Default: write raw = yes + + diff --git a/docs/docbook/smbdotconf/security/adminusers.xml b/docs/docbook/smbdotconf/security/adminusers.xml new file mode 100644 index 0000000000..2e1abaf6e1 --- /dev/null +++ b/docs/docbook/smbdotconf/security/adminusers.xml @@ -0,0 +1,15 @@ + + admin users (S) + This is a list of users who will be granted + administrative privileges on the share. This means that they + will do all file operations as the super-user (root). + + You should use this option very carefully, as any user in + this list will be able to do anything they like on the share, + irrespective of file permissions. + + Default: no admin users + + Example: admin users = jason + + diff --git a/docs/docbook/smbdotconf/security/algorithmicridbase.xml b/docs/docbook/smbdotconf/security/algorithmicridbase.xml new file mode 100644 index 0000000000..3c2bf8686e --- /dev/null +++ b/docs/docbook/smbdotconf/security/algorithmicridbase.xml @@ -0,0 +1,22 @@ + + algorithmic rid base (G) + This determines how Samba will use its + algorithmic mapping from uids/gid to the RIDs needed to construct + NT Security Identifiers. + + Setting this option to a larger value could be useful to sites + transitioning from WinNT and Win2k, as existing user and + group rids would otherwise clash with sytem users etc. + + + All UIDs and GIDs must be able to be resolved into SIDs for + the correct operation of ACLs on the server. As such the algorithmic + mapping can't be 'turned off', but pushing it 'out of the way' should + resolve the issues. Users and groups can then be assigned 'low' RIDs + in arbitary-rid supporting backends. + + Default: algorithmic rid base = 1000 + + Example: algorithmic rid base = 100000 + + diff --git a/docs/docbook/smbdotconf/security/allowhosts.xml b/docs/docbook/smbdotconf/security/allowhosts.xml new file mode 100644 index 0000000000..7fd2f426f8 --- /dev/null +++ b/docs/docbook/smbdotconf/security/allowhosts.xml @@ -0,0 +1,5 @@ + + allow hosts (S) + Synonym for + hosts allow. + diff --git a/docs/docbook/smbdotconf/security/allowtrusteddomains.xml b/docs/docbook/smbdotconf/security/allowtrusteddomains.xml new file mode 100644 index 0000000000..35dcd76cbd --- /dev/null +++ b/docs/docbook/smbdotconf/security/allowtrusteddomains.xml @@ -0,0 +1,22 @@ + + allow trusted domains (G) + This option only takes effect when the security option is set to + server or domain. + If it is set to no, then attempts to connect to a resource from + a domain or workgroup other than the one which smbd is running + in will fail, even if that domain is trusted by the remote server + doing the authentication. + + This is useful if you only want your Samba server to + serve resources to users in the domain it is a member of. As + an example, suppose that there are two domains DOMA and DOMB. DOMB + is trusted by DOMA, which contains the Samba server. Under normal + circumstances, a user with an account in DOMB can then access the + resources of a UNIX account with the same account name on the + Samba server even if they do not have an account in DOMA. This + can make implementing a security boundary difficult. + + Default: allow trusted domains = yes + + + diff --git a/docs/docbook/smbdotconf/security/authmethods.xml b/docs/docbook/smbdotconf/security/authmethods.xml new file mode 100644 index 0000000000..2e569558a0 --- /dev/null +++ b/docs/docbook/smbdotconf/security/authmethods.xml @@ -0,0 +1,16 @@ + + auth methods (G) + This option allows the administrator to chose what + authentication methods smbd will use when authenticating + a user. This option defaults to sensible values based on + security. + + Each entry in the list attempts to authenticate the user in turn, until + the user authenticates. In practice only one method will ever actually + be able to complete the authentication. + + + Default: auth methods = <empty string> + Example: auth methods = guest sam ntdomain + + diff --git a/docs/docbook/smbdotconf/security/createmask.xml b/docs/docbook/smbdotconf/security/createmask.xml new file mode 100644 index 0000000000..9a197bf7c3 --- /dev/null +++ b/docs/docbook/smbdotconf/security/createmask.xml @@ -0,0 +1,39 @@ + + create mask (S) + A synonym for this parameter is + create mode + . + + When a file is created, the necessary permissions are + calculated according to the mapping from DOS modes to UNIX + permissions, and the resulting UNIX mode is then bit-wise 'AND'ed + with this parameter. This parameter may be thought of as a bit-wise + MASK for the UNIX modes of a file. Any bit not + set here will be removed from the modes set on a file when it is + created. + + The default value of this parameter removes the + 'group' and 'other' write and execute bits from the UNIX modes. + + Following this Samba will bit-wise 'OR' the UNIX mode created + from this parameter with the value of the force create mode + parameter which is set to 000 by default. + + This parameter does not affect directory modes. See the + parameter directory mode + for details. + + See also the force + create mode parameter for forcing particular mode + bits to be set on created files. See also the + directory mode parameter for masking + mode bits on created directories. See also the + inherit permissions parameter. + + Note that this parameter does not apply to permissions + set by Windows NT/2000 ACL editors. If the administrator wishes to enforce + a mask on access control lists also, they need to set the security mask. + + Default: create mask = 0744 + Example: create mask = 0775 + diff --git a/docs/docbook/smbdotconf/security/createmode.xml b/docs/docbook/smbdotconf/security/createmode.xml new file mode 100644 index 0000000000..7e78ab0181 --- /dev/null +++ b/docs/docbook/smbdotconf/security/createmode.xml @@ -0,0 +1,5 @@ + + create mode (S) + This is a synonym for + create mask. + diff --git a/docs/docbook/smbdotconf/security/denyhosts.xml b/docs/docbook/smbdotconf/security/denyhosts.xml new file mode 100644 index 0000000000..f50fb33d33 --- /dev/null +++ b/docs/docbook/smbdotconf/security/denyhosts.xml @@ -0,0 +1,5 @@ + + deny hosts (S) + Synonym for hosts + deny. + diff --git a/docs/docbook/smbdotconf/security/directorymask.xml b/docs/docbook/smbdotconf/security/directorymask.xml new file mode 100644 index 0000000000..0844733ede --- /dev/null +++ b/docs/docbook/smbdotconf/security/directorymask.xml @@ -0,0 +1,43 @@ + + directory mask (S) + This parameter is the octal modes which are + used when converting DOS modes to UNIX modes when creating UNIX + directories. + + When a directory is created, the necessary permissions are + calculated according to the mapping from DOS modes to UNIX permissions, + and the resulting UNIX mode is then bit-wise 'AND'ed with this + parameter. This parameter may be thought of as a bit-wise MASK for + the UNIX modes of a directory. Any bit not set + here will be removed from the modes set on a directory when it is + created. + + The default value of this parameter removes the 'group' + and 'other' write bits from the UNIX mode, allowing only the + user who owns the directory to modify it. + + Following this Samba will bit-wise 'OR' the UNIX mode + created from this parameter with the value of the force directory mode + parameter. This parameter is set to 000 by + default (i.e. no extra mode bits are added). + + Note that this parameter does not apply to permissions + set by Windows NT/2000 ACL editors. If the administrator wishes to enforce + a mask on access control lists also, they need to set the directory security mask. + + See the force + directory mode parameter to cause particular mode + bits to always be set on created directories. + + See also the create mode + parameter for masking mode bits on created files, + and the directory + security mask parameter. + + Also refer to the + inherit permissions parameter. + + Default: directory mask = 0755 + Example: directory mask = 0775 + + diff --git a/docs/docbook/smbdotconf/security/directorymode.xml b/docs/docbook/smbdotconf/security/directorymode.xml new file mode 100644 index 0000000000..9678cd91ad --- /dev/null +++ b/docs/docbook/smbdotconf/security/directorymode.xml @@ -0,0 +1,5 @@ + + directory mode (S) + Synonym for + directory mask + diff --git a/docs/docbook/smbdotconf/security/directorysecuritymask.xml b/docs/docbook/smbdotconf/security/directorysecuritymask.xml new file mode 100644 index 0000000000..76d153f6f4 --- /dev/null +++ b/docs/docbook/smbdotconf/security/directorysecuritymask.xml @@ -0,0 +1,32 @@ + + directory security mask (S) + This parameter controls what UNIX permission bits + can be modified when a Windows NT client is manipulating the UNIX + permission on a directory using the native NT security dialog + box. + + This parameter is applied as a mask (AND'ed with) to + the changed permission bits, thus preventing any bits not in + this mask from being modified. Essentially, zero bits in this + mask may be treated as a set of bits the user is not allowed + to change. + + If not set explicitly this parameter is set to 0777 + meaning a user is allowed to modify all the user/group/world + permissions on a directory. + + Note that users who can access the + Samba server through other means can easily bypass this restriction, + so it is primarily useful for standalone "appliance" systems. + Administrators of most normal systems will probably want to leave + it as the default of 0777. + + See also the + force directory security mode, security mask, + force security mode + parameters. + + Default: directory security mask = 0777 + Example: directory security mask = 0700 + + diff --git a/docs/docbook/smbdotconf/security/encryptpasswords.xml b/docs/docbook/smbdotconf/security/encryptpasswords.xml new file mode 100644 index 0000000000..d7ceb8d598 --- /dev/null +++ b/docs/docbook/smbdotconf/security/encryptpasswords.xml @@ -0,0 +1,21 @@ + + encrypt passwords (G) + This boolean controls whether encrypted passwords + will be negotiated with the client. Note that Windows NT 4.0 SP3 and + above and also Windows 98 will by default expect encrypted passwords + unless a registry entry is changed. To use encrypted passwords in + Samba see the file ENCRYPTION.txt in the Samba documentation + directory docs/ shipped with the source code. + + In order for encrypted passwords to work correctly + smbd + 8 must either + have access to a local smbpasswd + 5 file (see the smbpasswd + 8 program for information on how to set up + and maintain this file), or set the security = [server|domain|ads] parameter which + causes smbd to authenticate against another + server. + + Default: encrypt passwords = yes + diff --git a/docs/docbook/smbdotconf/security/forcecreatemode.xml b/docs/docbook/smbdotconf/security/forcecreatemode.xml new file mode 100644 index 0000000000..238340d7c5 --- /dev/null +++ b/docs/docbook/smbdotconf/security/forcecreatemode.xml @@ -0,0 +1,25 @@ + + force create mode (S) + This parameter specifies a set of UNIX mode bit + permissions that will always be set on a + file created by Samba. This is done by bitwise 'OR'ing these bits onto + the mode bits of a file that is being created or having its + permissions changed. The default for this parameter is (in octal) + 000. The modes in this parameter are bitwise 'OR'ed onto the file + mode after the mask set in the create mask + parameter is applied. + + See also the parameter create + mask for details on masking mode bits on files. + + See also the inherit + permissions parameter. + + Default: force create mode = 000 + Example: force create mode = 0755 + + would force all created files to have read and execute + permissions set for 'group' and 'other' as well as the + read/write/execute bits set for the 'user'. + + diff --git a/docs/docbook/smbdotconf/security/forcedirectorymode.xml b/docs/docbook/smbdotconf/security/forcedirectorymode.xml new file mode 100644 index 0000000000..460a7fc6f2 --- /dev/null +++ b/docs/docbook/smbdotconf/security/forcedirectorymode.xml @@ -0,0 +1,26 @@ + + force directory mode (S) + This parameter specifies a set of UNIX mode bit + permissions that will always be set on a directory + created by Samba. This is done by bitwise 'OR'ing these bits onto the + mode bits of a directory that is being created. The default for this + parameter is (in octal) 0000 which will not add any extra permission + bits to a created directory. This operation is done after the mode + mask in the parameter directory mask is + applied. + + See also the parameter + directory mask for details on masking mode bits + on created directories. + + See also the + inherit permissions parameter. + + Default: force directory mode = 000 + Example: force directory mode = 0755 + + would force all created directories to have read and execute + permissions set for 'group' and 'other' as well as the + read/write/execute bits set for the 'user'. + + diff --git a/docs/docbook/smbdotconf/security/forcedirectorysecuritymode.xml b/docs/docbook/smbdotconf/security/forcedirectorysecuritymode.xml new file mode 100644 index 0000000000..a01b297b05 --- /dev/null +++ b/docs/docbook/smbdotconf/security/forcedirectorysecuritymode.xml @@ -0,0 +1,32 @@ + + force directory security mode (S) + This parameter controls what UNIX permission bits + can be modified when a Windows NT client is manipulating the UNIX + permission on a directory using the native NT security dialog box. + + This parameter is applied as a mask (OR'ed with) to the + changed permission bits, thus forcing any bits in this mask that + the user may have modified to be on. Essentially, one bits in this + mask may be treated as a set of bits that, when modifying security + on a directory, the user has always set to be 'on'. + + If not set explicitly this parameter is 000, which + allows a user to modify all the user/group/world permissions on a + directory without restrictions. + + Note that users who can access the + Samba server through other means can easily bypass this restriction, + so it is primarily useful for standalone "appliance" systems. + Administrators of most normal systems will probably want to leave + it set as 0000. + + See also the + directory security mask, + security mask, + force security mode + parameters. + + Default: force directory security mode = 0 + Example: force directory security mode = 700 + + diff --git a/docs/docbook/smbdotconf/security/forcegroup.xml b/docs/docbook/smbdotconf/security/forcegroup.xml new file mode 100644 index 0000000000..abfec79e03 --- /dev/null +++ b/docs/docbook/smbdotconf/security/forcegroup.xml @@ -0,0 +1,35 @@ + + force group (S) + This specifies a UNIX group name that will be + assigned as the default primary group for all users connecting + to this service. This is useful for sharing files by ensuring + that all access to files on service will use the named group for + their permissions checking. Thus, by assigning permissions for this + group to the files and directories within this service the Samba + administrator can restrict or allow sharing of these files. + + In Samba 2.0.5 and above this parameter has extended + functionality in the following way. If the group name listed here + has a '+' character prepended to it then the current user accessing + the share only has the primary group default assigned to this group + if they are already assigned as a member of that group. This allows + an administrator to decide that only users who are already in a + particular group will create files with group ownership set to that + group. This gives a finer granularity of ownership assignment. For + example, the setting force group = +sys means + that only users who are already in group sys will have their default + primary group assigned to sys when accessing this Samba share. All + other users will retain their ordinary primary group. + + If the force user + parameter is also set the group specified in + force group will override the primary group + set in force user. + + See also force + user. + + Default: no forced group + Example: force group = agroup + + diff --git a/docs/docbook/smbdotconf/security/forcesecuritymode.xml b/docs/docbook/smbdotconf/security/forcesecuritymode.xml new file mode 100644 index 0000000000..2db50f1ce3 --- /dev/null +++ b/docs/docbook/smbdotconf/security/forcesecuritymode.xml @@ -0,0 +1,33 @@ + + force security mode (S) + This parameter controls what UNIX permission + bits can be modified when a Windows NT client is manipulating + the UNIX permission on a file using the native NT security dialog + box. + + This parameter is applied as a mask (OR'ed with) to the + changed permission bits, thus forcing any bits in this mask that + the user may have modified to be on. Essentially, one bits in this + mask may be treated as a set of bits that, when modifying security + on a file, the user has always set to be 'on'. + + If not set explicitly this parameter is set to 0, + and allows a user to modify all the user/group/world permissions on a file, + with no restrictions. + + Note that users who can access + the Samba server through other means can easily bypass this restriction, + so it is primarily useful for standalone "appliance" systems. + Administrators of most normal systems will probably want to leave + this set to 0000. + + See also the + force directory security mode, + directory security + mask, + security mask parameters. + + Default: force security mode = 0 + Example: force security mode = 700 + + diff --git a/docs/docbook/smbdotconf/security/forceuser.xml b/docs/docbook/smbdotconf/security/forceuser.xml new file mode 100644 index 0000000000..4747db13fe --- /dev/null +++ b/docs/docbook/smbdotconf/security/forceuser.xml @@ -0,0 +1,25 @@ + + force user (S) + This specifies a UNIX user name that will be + assigned as the default user for all users connecting to this service. + This is useful for sharing files. You should also use it carefully + as using it incorrectly can cause security problems. + + This user name only gets used once a connection is established. + Thus clients still need to connect as a valid user and supply a + valid password. Once connected, all file operations will be performed + as the "forced user", no matter what username the client connected + as. This can be very useful. + + In Samba 2.0.5 and above this parameter also causes the + primary group of the forced user to be used as the primary group + for all file activity. Prior to 2.0.5 the primary group was left + as the primary group of the connecting user (this was a bug). + + See also force group + + + Default: no forced user + Example: force user = auser + + diff --git a/docs/docbook/smbdotconf/security/group.xml b/docs/docbook/smbdotconf/security/group.xml new file mode 100644 index 0000000000..afc410ce34 --- /dev/null +++ b/docs/docbook/smbdotconf/security/group.xml @@ -0,0 +1,5 @@ + + group (S) + Synonym for force + group. + diff --git a/docs/docbook/smbdotconf/security/guestaccount.xml b/docs/docbook/smbdotconf/security/guestaccount.xml new file mode 100644 index 0000000000..ab15c4460d --- /dev/null +++ b/docs/docbook/smbdotconf/security/guestaccount.xml @@ -0,0 +1,27 @@ + + guest account (S) + This is a username which will be used for access + to services which are specified as + guest ok (see below). Whatever privileges this + user has will be available to any client connecting to the guest service. + Typically this user will exist in the password file, but will not + have a valid login. The user account "ftp" is often a good choice + for this parameter. If a username is specified in a given service, + the specified username overrides this one. + + One some systems the default guest account "nobody" may not + be able to print. Use another account in this case. You should test + this by trying to log in as your guest user (perhaps by using the + su - command) and trying to print using the + system print command such as lpr(1) or + lp(1). + + This parameter does not accept % macros, because + many parts of the system require this value to be + constant for correct operation. + + Default: specified at compile time, usually + "nobody" + + Example: guest account = ftp + diff --git a/docs/docbook/smbdotconf/security/guestok.xml b/docs/docbook/smbdotconf/security/guestok.xml new file mode 100644 index 0000000000..2b7a8cee8a --- /dev/null +++ b/docs/docbook/smbdotconf/security/guestok.xml @@ -0,0 +1,17 @@ + + guest ok (S) + If this parameter is yes for + a service, then no password is required to connect to the service. + Privileges will be those of the + guest account. + + This paramater nullifies the benifits of setting + restrict + anonymous = 2 + + See the section below on + security for more information about this option. + + + Default: guest ok = no + diff --git a/docs/docbook/smbdotconf/security/guestonly.xml b/docs/docbook/smbdotconf/security/guestonly.xml new file mode 100644 index 0000000000..ac7f62ad68 --- /dev/null +++ b/docs/docbook/smbdotconf/security/guestonly.xml @@ -0,0 +1,13 @@ + + guest only (S) + If this parameter is yes for + a service, then only guest connections to the service are permitted. + This parameter will have no effect if + guest ok is not set for the service. + + See the section below on + security for more information about this option. + + + Default: guest only = no + diff --git a/docs/docbook/smbdotconf/security/hostsallow.xml b/docs/docbook/smbdotconf/security/hostsallow.xml new file mode 100644 index 0000000000..ea91b73903 --- /dev/null +++ b/docs/docbook/smbdotconf/security/hostsallow.xml @@ -0,0 +1,60 @@ + + hosts allow (S) + A synonym for this parameter is allow + hosts. + + This parameter is a comma, space, or tab delimited + set of hosts which are permitted to access a service. + + If specified in the [global] section then it will + apply to all services, regardless of whether the individual + service has a different setting. + + You can specify the hosts by name or IP number. For + example, you could restrict access to only the hosts on a + Class C subnet with something like allow hosts = 150.203.5. + . The full syntax of the list is described in the man + page hosts_access(5). Note that this man + page may not be present on your system, so a brief description will + be given here also. + + Note that the localhost address 127.0.0.1 will always + be allowed access unless specifically denied by a hosts deny option. + + You can also specify hosts by network/netmask pairs and + by netgroup names if your system supports netgroups. The + EXCEPT keyword can also be used to limit a + wildcard list. The following examples may provide some help: + + Example 1: allow all IPs in 150.203.*.*; except one + + hosts allow = 150.203. EXCEPT 150.203.6.66 + + Example 2: allow hosts that match the given network/netmask + + hosts allow = 150.203.15.0/255.255.255.0 + + Example 3: allow a couple of hosts + + hosts allow = lapland, arvidsjaur + + Example 4: allow only hosts in NIS netgroup "foonet", but + deny access from one particular host + + hosts allow = @foonet + + hosts deny = pirate + + Note that access still requires suitable user-level passwords. + + See testparm + 1 for a way of testing your host access + to see if it does what you expect. + + Default: none (i.e., all hosts permitted access) + + + Example: allow hosts = 150.203.5. myhost.mynet.edu.au + + + diff --git a/docs/docbook/smbdotconf/security/hostsdeny.xml b/docs/docbook/smbdotconf/security/hostsdeny.xml new file mode 100644 index 0000000000..f37e2b7e4d --- /dev/null +++ b/docs/docbook/smbdotconf/security/hostsdeny.xml @@ -0,0 +1,14 @@ + + hosts deny (S) + The opposite of hosts allow + - hosts listed here are NOT permitted access to + services unless the specific services have their own lists to override + this one. Where the lists conflict, the allow + list takes precedence. + + Default: none (i.e., no hosts specifically excluded) + + + Example: hosts deny = 150.203.4. badhost.mynet.edu.au + + diff --git a/docs/docbook/smbdotconf/security/hostsequiv.xml b/docs/docbook/smbdotconf/security/hostsequiv.xml new file mode 100644 index 0000000000..68d6d628e8 --- /dev/null +++ b/docs/docbook/smbdotconf/security/hostsequiv.xml @@ -0,0 +1,26 @@ + + hosts equiv (G) + If this global parameter is a non-null string, + it specifies the name of a file to read for the names of hosts + and users who will be allowed access without specifying a password. + + + This is not be confused with + hosts allow which is about hosts + access to services and is more useful for guest services. + hosts equiv may be useful for NT clients which will + not supply passwords to Samba. + + NOTE : The use of hosts equiv + can be a major security hole. This is because you are + trusting the PC to supply the correct username. It is very easy to + get a PC to supply a false username. I recommend that the + hosts equiv option be only used if you really + know what you are doing, or perhaps on a home network where you trust + your spouse and kids. And only if you really trust + them :-). + + Default: no host equivalences + Example: hosts equiv = /etc/hosts.equiv + + diff --git a/docs/docbook/smbdotconf/security/inheritacls.xml b/docs/docbook/smbdotconf/security/inheritacls.xml new file mode 100644 index 0000000000..f70c0d9165 --- /dev/null +++ b/docs/docbook/smbdotconf/security/inheritacls.xml @@ -0,0 +1,14 @@ + + inherit acls (S) + This parameter can be used to ensure + that if default acls exist on parent directories, + they are always honored when creating a subdirectory. + The default behavior is to use the mode specified + when creating the directory. Enabling this option + sets the mode to 0777, thus guaranteeing that + default directory acls are propagated. + + + Default: inherit acls = no + + diff --git a/docs/docbook/smbdotconf/security/inheritpermissions.xml b/docs/docbook/smbdotconf/security/inheritpermissions.xml new file mode 100644 index 0000000000..34fade33d0 --- /dev/null +++ b/docs/docbook/smbdotconf/security/inheritpermissions.xml @@ -0,0 +1,36 @@ + + inherit permissions (S) + The permissions on new files and directories + are normally governed by + create mask, + directory mask, force create mode + and force + directory mode but the boolean inherit + permissions parameter overrides this. + + New directories inherit the mode of the parent directory, + including bits such as setgid. + + New files inherit their read/write bits from the parent + directory. Their execute bits continue to be determined by + map archive + , map hidden + and map system + as usual. + + Note that the setuid bit is never set via + inheritance (the code explicitly prohibits this). + + This can be particularly useful on large systems with + many users, perhaps several thousand, to allow a single [homes] + share to be used flexibly by each user. + + See also create mask + , + directory mask, + force create mode and force directory mode + . + + Default: inherit permissions = no + + diff --git a/docs/docbook/smbdotconf/security/invalidusers.xml b/docs/docbook/smbdotconf/security/invalidusers.xml new file mode 100644 index 0000000000..34e534ff28 --- /dev/null +++ b/docs/docbook/smbdotconf/security/invalidusers.xml @@ -0,0 +1,33 @@ + + invalid users (S) + This is a list of users that should not be allowed + to login to this service. This is really a paranoid + check to absolutely ensure an improper setting does not breach + your security. + + A name starting with a '@' is interpreted as an NIS + netgroup first (if your system supports NIS), and then as a UNIX + group if the name was not found in the NIS netgroup database. + + A name starting with '+' is interpreted only + by looking in the UNIX group database. A name starting with + '&' is interpreted only by looking in the NIS netgroup database + (this requires NIS to be working on your system). The characters + '+' and '&' may be used at the start of the name in either order + so the value +&group means check the + UNIX group database, followed by the NIS netgroup database, and + the value &+group means check the NIS + netgroup database, followed by the UNIX group database (the + same as the '@' prefix). + + The current servicename is substituted for %S. + This is useful in the [homes] section. + + See also valid users + . + + Default: no invalid users + Example: invalid users = root fred admin @wheel + + + diff --git a/docs/docbook/smbdotconf/security/lanmanauth.xml b/docs/docbook/smbdotconf/security/lanmanauth.xml new file mode 100644 index 0000000000..851b1ae4ac --- /dev/null +++ b/docs/docbook/smbdotconf/security/lanmanauth.xml @@ -0,0 +1,11 @@ + + lanman auth (G) + This parameter determines whether or not smbd + 8 will attempt to authenticate users + using the LANMAN password hash. If disabled, only clients which support NT + password hashes (e.g. Windows NT/2000 clients, smbclient, etc... but not + Windows 95/98 or the MS DOS network client) will be able to connect to the Samba host. + + Default : lanman auth = yes + + diff --git a/docs/docbook/smbdotconf/security/maptoguest.xml b/docs/docbook/smbdotconf/security/maptoguest.xml new file mode 100644 index 0000000000..966260a9b1 --- /dev/null +++ b/docs/docbook/smbdotconf/security/maptoguest.xml @@ -0,0 +1,53 @@ + + map to guest (G) + This parameter is only useful in + security modes other than security = share + - i.e. user, server, + and domain. + + This parameter can take three different values, which tell + smbd + 8 what to do with user + login requests that don't match a valid UNIX user in some way. + + The three settings are : + + + Never - Means user login + requests with an invalid password are rejected. This is the + default. + + Bad User - Means user + logins with an invalid password are rejected, unless the username + does not exist, in which case it is treated as a guest login and + mapped into the + guest account. + + Bad Password - Means user logins + with an invalid password are treated as a guest login and mapped + into the guest account. Note that + this can cause problems as it means that any user incorrectly typing + their password will be silently logged on as "guest" - and + will not know the reason they cannot access files they think + they should - there will have been no message given to them + that they got their password wrong. Helpdesk services will + hate you if you set the map to + guest parameter this way :-). + + + Note that this parameter is needed to set up "Guest" + share services when using security modes other than + share. This is because in these modes the name of the resource being + requested is not sent to the server until after + the server has successfully authenticated the client so the server + cannot make authentication decisions at the correct time (connection + to the share) for "Guest" shares. + + For people familiar with the older Samba releases, this + parameter maps to the old compile-time setting of the + GUEST_SESSSETUP value in local.h. + + Default: map to guest = Never + Example: map to guest = Bad User + + diff --git a/docs/docbook/smbdotconf/security/minpasswdlength.xml b/docs/docbook/smbdotconf/security/minpasswdlength.xml new file mode 100644 index 0000000000..8e52b923fb --- /dev/null +++ b/docs/docbook/smbdotconf/security/minpasswdlength.xml @@ -0,0 +1,6 @@ + + min passwd length (G) + Synonym for + min password length. + + diff --git a/docs/docbook/smbdotconf/security/minpasswordlength.xml b/docs/docbook/smbdotconf/security/minpasswordlength.xml new file mode 100644 index 0000000000..da1e65a55b --- /dev/null +++ b/docs/docbook/smbdotconf/security/minpasswordlength.xml @@ -0,0 +1,14 @@ + + min password length (G) + This option sets the minimum length in characters + of a plaintext password that smbd will accept when performing + UNIX password changing. + + See also unix + password sync, + passwd program and passwd chat debug + . + + Default: min password length = 5 + + diff --git a/docs/docbook/smbdotconf/security/nonunixaccountrange.xml b/docs/docbook/smbdotconf/security/nonunixaccountrange.xml new file mode 100644 index 0000000000..a8e426649e --- /dev/null +++ b/docs/docbook/smbdotconf/security/nonunixaccountrange.xml @@ -0,0 +1,21 @@ + + non unix account range (G) + The non unix account range parameter specifies + the range of 'user ids' that are allocated by the various 'non unix + account' passdb backends. These backends allow + the storage of passwords for users who don't exist in /etc/passwd. + This is most often used for machine account creation. + This range of ids should have no existing local or NIS users within + it as strange conflicts can occur otherwise. + + NOTE: These userids never appear on the system and Samba will never + 'become' these users. They are used only to ensure that the algorithmic + RID mapping does not conflict with normal users. + + + Default: non unix account range = <empty string> + + + Example: non unix account range = 10000-20000 + + diff --git a/docs/docbook/smbdotconf/security/ntlmauth.xml b/docs/docbook/smbdotconf/security/ntlmauth.xml new file mode 100644 index 0000000000..a3b8caf062 --- /dev/null +++ b/docs/docbook/smbdotconf/security/ntlmauth.xml @@ -0,0 +1,16 @@ + + ntlm auth (G) + This parameter determines + whether or not smbd + 8 will + attempt to authenticate users using the NTLM password hash. + If disabled, only the lanman password hashes will be used. + + + Please note that at least this option or lanman auth should + be enabled in order to be able to log in. + + + Default : ntlm auth = yes + + diff --git a/docs/docbook/smbdotconf/security/nullpasswords.xml b/docs/docbook/smbdotconf/security/nullpasswords.xml new file mode 100644 index 0000000000..40b687fceb --- /dev/null +++ b/docs/docbook/smbdotconf/security/nullpasswords.xml @@ -0,0 +1,11 @@ + + null passwords (G) + Allow or disallow client access to accounts + that have null passwords. + + See also smbpasswd + 5. + + Default: null passwords = no + + diff --git a/docs/docbook/smbdotconf/security/obeypamrestrictions.xml b/docs/docbook/smbdotconf/security/obeypamrestrictions.xml new file mode 100644 index 0000000000..92a6bce22d --- /dev/null +++ b/docs/docbook/smbdotconf/security/obeypamrestrictions.xml @@ -0,0 +1,15 @@ + + obey pam restrictions (G) + When Samba 2.2 is configured to enable PAM support + (i.e. --with-pam), this parameter will control whether or not Samba + should obey PAM's account and session management directives. The + default behavior is to use PAM for clear text authentication only + and to ignore any account or session management. Note that Samba + always ignores PAM for authentication in the case of encrypt passwords = yes + . The reason is that PAM modules cannot support the challenge/response + authentication mechanism needed in the presence of SMB password encryption. + + + Default: obey pam restrictions = no + + diff --git a/docs/docbook/smbdotconf/security/onlyguest.xml b/docs/docbook/smbdotconf/security/onlyguest.xml new file mode 100644 index 0000000000..018fa1a0b5 --- /dev/null +++ b/docs/docbook/smbdotconf/security/onlyguest.xml @@ -0,0 +1,6 @@ + + only guest (S) + A synonym for + guest only. + + diff --git a/docs/docbook/smbdotconf/security/onlyuser.xml b/docs/docbook/smbdotconf/security/onlyuser.xml new file mode 100644 index 0000000000..d0bbac7541 --- /dev/null +++ b/docs/docbook/smbdotconf/security/onlyuser.xml @@ -0,0 +1,24 @@ + + only user (S) + This is a boolean option that controls whether + connections with usernames not in the user + list will be allowed. By default this option is disabled so that a + client can supply a username to be used by the server. Enabling + this parameter will force the server to only use the login + names from the user list and is only really + useful in share level + security. + + Note that this also means Samba won't try to deduce + usernames from the service name. This can be annoying for + the [homes] section. To get around this you could use user = + %S which means your user list + will be just the service name, which for home directories is the + name of the user. + + See also the user + parameter. + + Default: only user = no + + diff --git a/docs/docbook/smbdotconf/security/pampasswordchange.xml b/docs/docbook/smbdotconf/security/pampasswordchange.xml new file mode 100644 index 0000000000..8f0e91ae2d --- /dev/null +++ b/docs/docbook/smbdotconf/security/pampasswordchange.xml @@ -0,0 +1,16 @@ + + pam password change (G) + With the addition of better PAM support in Samba 2.2, + this parameter, it is possible to use PAM's password change control + flag for Samba. If enabled, then PAM will be used for password + changes when requested by an SMB client instead of the program listed in + passwd program. + It should be possible to enable this without changing your + passwd chat + parameter for most setups. + + + Default: pam password change = no + + + diff --git a/docs/docbook/smbdotconf/security/passdbbackend.xml b/docs/docbook/smbdotconf/security/passdbbackend.xml new file mode 100644 index 0000000000..918c802e78 --- /dev/null +++ b/docs/docbook/smbdotconf/security/passdbbackend.xml @@ -0,0 +1,91 @@ + + passdb backend (G) + This option allows the administrator to chose which backends to retrieve and store passwords with. This allows (for example) both + smbpasswd and tdbsam to be used without a recompile. + Multiple backends can be specified, separated by spaces. The backends will be searched in the order they are specified. New users are always added to the first backend specified. + Experimental backends must still be selected + (eg --with-tdbsam) at configure time. + + + This parameter is in two parts, the backend's name, and a 'location' + string that has meaning only to that particular backed. These are separated + by a : character. + + Available backends can include: + + smbpasswd - The default smbpasswd + backend. Takes a path to the smbpasswd file as an optional argument. + + smbpasswd_nua - The smbpasswd + backend, but with support for 'not unix accounts'. + Takes a path to the smbpasswd file as an optional argument. + See also + non unix account range + + tdbsam - The TDB based password storage + backend. Takes a path to the TDB as an optional argument (defaults to passdb.tdb + in the + private dir directory. + + tdbsam_nua - The TDB based password storage + backend, with non unix account support. Takes a path to the TDB as an optional argument (defaults to passdb.tdb + in the + private dir directory. + See also + non unix account range + + ldapsam - The LDAP based passdb + backend. Takes an LDAP URL as an optional argument (defaults to + ldap://localhost) + + ldapsam_nua - The LDAP based passdb + backend, with non unix account support. Takes an LDAP URL as an optional argument (defaults to + ldap://localhost) + + Note: In this module, any account without a matching POSIX account is regarded + as 'non unix'. + + See also + non unix account + range + + LDAP connections should be secured where + possible. This may be done using either + Start-TLS (see + ldap ssl) or by + specifying ldaps:// in + the URL argument. + + + nisplussam - The NIS+ based passdb backend. Takes name NIS domain as an optional argument. Only works with sun NIS+ servers. + + plugin - Allows Samba to load an + arbitary passdb backend from the .so specified as a compulsary argument. + + + Any characters after the (optional) second : are passed to the plugin + for its own processing + + + unixsam - Allows samba to map all (other) available unix users + + This backend uses the standard unix database for retrieving users. Users included + in this pdb are NOT listed in samba user listings and users included in this pdb won't be + able to login. The use of this backend is to always be able to display the owner of a file + on the samba server - even when the user doesn't have a 'real' samba account in one of the + other passdb backends. + + + This backend should always be the last backend listed, since it contains all users in + the unix passdb and might 'override' mappings if specified earlier. It's meant to only return + accounts for users that aren't covered by the previous backends. + + + + + Default: passdb backend = smbpasswd unixsam + Example: passdb backend = tdbsam:/etc/samba/private/passdb.tdb smbpasswd:/etc/samba/smbpasswd unixsam + Example: passdb backend = ldapsam_nua:ldaps://ldap.example.com unixsam + Example: passdb backend = plugin:/usr/local/samba/lib/my_passdb.so:my_plugin_args tdbsam:/etc/samba/private/passdb.tdb + + diff --git a/docs/docbook/smbdotconf/security/passwdchat.xml b/docs/docbook/smbdotconf/security/passwdchat.xml new file mode 100644 index 0000000000..922f1a878c --- /dev/null +++ b/docs/docbook/smbdotconf/security/passwdchat.xml @@ -0,0 +1,58 @@ + + passwd chat (G) + This string controls the "chat" + conversation that takes places between smbd + 8 and the local password changing + program to change the user's password. The string describes a + sequence of response-receive pairs that smbd + 8 uses to determine what to send to the + passwd program + and what to expect back. If the expected output is not + received then the password is not changed. + + This chat sequence is often quite site specific, depending + on what local methods are used for password control (such as NIS + etc). + Note that this parameter only is only used if the unix + password sync parameter is set to yes. This + sequence is then called AS ROOT when the SMB password + in the smbpasswd file is being changed, without access to the old + password cleartext. This means that root must be able to reset the user's password + without knowing the text of the previous password. In the presence of NIS/YP, + this means that the passwd program must be + executed on the NIS master. + + + + The string can contain the macro %n which is substituted + for the new password. The chat sequence can also contain the standard + macros \\n, \\r, + \\t and \\s to give line-feed, + carriage-return, tab and space. The chat sequence string can also contain + a '*' which matches any sequence of characters. + Double quotes can be used to collect strings with spaces + in them into a single string. + + If the send string in any part of the chat sequence + is a full stop ".", then no string is sent. Similarly, + if the expect string is a full stop then no string is expected. + + If the pam + password change parameter is set to yes, the chat pairs + may be matched in any order, and success is determined by the PAM result, + not any particular output. The \n macro is ignored for PAM conversions. + + + See also unix password + sync, + passwd program , + passwd chat debug and + pam password change. + + Default: passwd chat = *new*password* %n\\n + *new*password* %n\\n *changed* + Example: passwd chat = "*Enter OLD password*" %o\\n + "*Enter NEW password*" %n\\n "*Reenter NEW password*" %n\\n "*Password + changed*" + + diff --git a/docs/docbook/smbdotconf/security/passwdchatdebug.xml b/docs/docbook/smbdotconf/security/passwdchatdebug.xml new file mode 100644 index 0000000000..a5771b72d2 --- /dev/null +++ b/docs/docbook/smbdotconf/security/passwdchatdebug.xml @@ -0,0 +1,25 @@ + + passwd chat debug (G) + This boolean specifies if the passwd chat script + parameter is run in debug mode. In this mode the + strings passed to and received from the passwd chat are printed + in the smbd + 8 log with a + debug level + of 100. This is a dangerous option as it will allow plaintext passwords + to be seen in the smbd log. It is available to help + Samba admins debug their passwd chat scripts + when calling the passwd program and should + be turned off after this has been done. This option has no effect if the + pam password change + paramter is set. This parameter is off by default. + + + See also passwd chat + , pam password change + , passwd program + . + + Default: passwd chat debug = no + + diff --git a/docs/docbook/smbdotconf/security/passwdprogram.xml b/docs/docbook/smbdotconf/security/passwdprogram.xml new file mode 100644 index 0000000000..dae24e22a1 --- /dev/null +++ b/docs/docbook/smbdotconf/security/passwdprogram.xml @@ -0,0 +1,35 @@ + + passwd program (G) + The name of a program that can be used to set + UNIX user passwords. Any occurrences of %u + will be replaced with the user name. The user name is checked for + existence before calling the password changing program. + + Also note that many passwd programs insist in reasonable + passwords, such as a minimum length, or the inclusion + of mixed case chars and digits. This can pose a problem as some clients + (such as Windows for Workgroups) uppercase the password before sending + it. + + Note that if the unix + password sync parameter is set to yes + then this program is called AS ROOT + before the SMB password in the smbpasswd(5) + file is changed. If this UNIX password change fails, then + smbd will fail to change the SMB password also + (this is by design). + + If the unix password sync parameter + is set this parameter MUST USE ABSOLUTE PATHS + for ALL programs called, and must be examined + for security implications. Note that by default unix + password sync is set to no. + + See also unix + password sync. + + Default: passwd program = /bin/passwd + Example: passwd program = /sbin/npasswd %u + + + diff --git a/docs/docbook/smbdotconf/security/passwordlevel.xml b/docs/docbook/smbdotconf/security/passwordlevel.xml new file mode 100644 index 0000000000..408082f838 --- /dev/null +++ b/docs/docbook/smbdotconf/security/passwordlevel.xml @@ -0,0 +1,40 @@ + + password level (G) + Some client/server combinations have difficulty + with mixed-case passwords. One offending client is Windows for + Workgroups, which for some reason forces passwords to upper + case when using the LANMAN1 protocol, but leaves them alone when + using COREPLUS! Another problem child is the Windows 95/98 + family of operating systems. These clients upper case clear + text passwords even when NT LM 0.12 selected by the protocol + negotiation request/response. + + This parameter defines the maximum number of characters + that may be upper case in passwords. + + For example, say the password given was "FRED". If + password level is set to 1, the following combinations + would be tried if "FRED" failed: + + "Fred", "fred", "fRed", "frEd","freD" + + If password level was set to 2, + the following combinations would also be tried: + + "FRed", "FrEd", "FreD", "fREd", "fReD", "frED", .. + + And so on. + + The higher value this parameter is set to the more likely + it is that a mixed case password will be matched against a single + case password. However, you should be aware that use of this + parameter reduces security and increases the time taken to + process a new connection. + + A value of zero will cause only two attempts to be + made - the password as is and the password in all-lower case. + + Default: password level = 0 + Example: password level = 4 + + diff --git a/docs/docbook/smbdotconf/security/passwordserver.xml b/docs/docbook/smbdotconf/security/passwordserver.xml new file mode 100644 index 0000000000..df50ac8f8a --- /dev/null +++ b/docs/docbook/smbdotconf/security/passwordserver.xml @@ -0,0 +1,92 @@ + + password server (G) + By specifying the name of another SMB server (such + as a WinNT box) with this option, and using security = domain + or security = server you can get Samba + to do all its username/password validation via a remote server. + + This option sets the name of the password server to use. + It must be a NetBIOS name, so if the machine's NetBIOS name is + different from its Internet name then you may have to add its NetBIOS + name to the lmhosts file which is stored in the same directory + as the smb.conf file. + + The name of the password server is looked up using the + parameter name + resolve order and so may resolved + by any method and order described in that parameter. + + The password server must be a machine capable of using + the "LM1.2X002" or the "NT LM 0.12" protocol, and it must be in + user level security mode. + + NOTE: Using a password server + means your UNIX box (running Samba) is only as secure as your + password server. DO NOT CHOOSE A PASSWORD SERVER THAT + YOU DON'T COMPLETELY TRUST. + + Never point a Samba server at itself for password + serving. This will cause a loop and could lock up your Samba + server! + + The name of the password server takes the standard + substitutions, but probably the only useful one is %m + , which means the Samba server will use the incoming + client as the password server. If you use this then you better + trust your clients, and you had better restrict them with hosts allow! + + If the security parameter is set to + domain, then the list of machines in this + option must be a list of Primary or Backup Domain controllers for the + Domain or the character '*', as the Samba server is effectively + in that domain, and will use cryptographically authenticated RPC calls + to authenticate the user logging on. The advantage of using + security = domain is that if you list several hosts in the + password server option then smbd + will try each in turn till it finds one that responds. This + is useful in case your primary server goes down. + + If the password server option is set + to the character '*', then Samba will attempt to auto-locate the + Primary or Backup Domain controllers to authenticate against by + doing a query for the name WORKGROUP<1C> + and then contacting each server returned in the list of IP + addresses from the name resolution source. + + If the list of servers contains both names and the '*' + character, the list is treated as a list of preferred + domain controllers, but an auto lookup of all remaining DC's + will be added to the list as well. Samba will not attempt to optimize + this list by locating the closest DC. + + If the security parameter is + set to server, then there are different + restrictions that security = domain doesn't + suffer from: + + + You may list several password servers in + the password server parameter, however if an + smbd makes a connection to a password server, + and then the password server fails, no more users will be able + to be authenticated from this smbd. This is a + restriction of the SMB/CIFS protocol when in security = server + mode and cannot be fixed in Samba. + + If you are using a Windows NT server as your + password server then you will have to ensure that your users + are able to login from the Samba server, as when in + security = server mode the network logon will appear to + come from there rather than from the users workstation. + + + See also the security + parameter. + + Default: password server = <empty string> + + Example: password server = NT-PDC, NT-BDC1, NT-BDC2, * + + Example: password server = * + + diff --git a/docs/docbook/smbdotconf/security/printeradmin.xml b/docs/docbook/smbdotconf/security/printeradmin.xml new file mode 100644 index 0000000000..7037facca0 --- /dev/null +++ b/docs/docbook/smbdotconf/security/printeradmin.xml @@ -0,0 +1,12 @@ + + printer admin (S) + This is a list of users that can do anything to + printers via the remote administration interfaces offered by MS-RPC + (usually using a NT workstation). Note that the root user always + has admin rights. + + Default: printer admin = <empty string> + + Example: printer admin = admin, @staff + + diff --git a/docs/docbook/smbdotconf/security/privatedir.xml b/docs/docbook/smbdotconf/security/privatedir.xml new file mode 100644 index 0000000000..ca22089122 --- /dev/null +++ b/docs/docbook/smbdotconf/security/privatedir.xml @@ -0,0 +1,10 @@ + + private dir (G) + This parameters defines the directory + smbd will use for storing such files as smbpasswd + and secrets.tdb. + + + Default :private dir = ${prefix}/private + + diff --git a/docs/docbook/smbdotconf/security/public.xml b/docs/docbook/smbdotconf/security/public.xml new file mode 100644 index 0000000000..a1f6a1ee29 --- /dev/null +++ b/docs/docbook/smbdotconf/security/public.xml @@ -0,0 +1,6 @@ + + public (S) + Synonym for guest + ok. + + diff --git a/docs/docbook/smbdotconf/security/readlist.xml b/docs/docbook/smbdotconf/security/readlist.xml new file mode 100644 index 0000000000..15d135d54e --- /dev/null +++ b/docs/docbook/smbdotconf/security/readlist.xml @@ -0,0 +1,17 @@ + + read list (S) + This is a list of users that are given read-only + access to a service. If the connecting user is in this list then + they will not be given write access, no matter what the read only + option is set to. The list can include group names using the + syntax described in the + invalid users parameter. + + See also the + write list parameter and the invalid users + parameter. + + Default: read list = <empty string> + Example: read list = mary, @students + + diff --git a/docs/docbook/smbdotconf/security/readonly.xml b/docs/docbook/smbdotconf/security/readonly.xml new file mode 100644 index 0000000000..02721935de --- /dev/null +++ b/docs/docbook/smbdotconf/security/readonly.xml @@ -0,0 +1,16 @@ + + read only (S) + An inverted synonym is + writeable. + + If this parameter is yes, then users + of a service may not create or modify files in the service's + directory. + + Note that a printable service (printable = yes) + will ALWAYS allow writing to the directory + (user privileges permitting), but only via spooling operations. + + Default: read only = yes + + diff --git a/docs/docbook/smbdotconf/security/restrictanonymous.xml b/docs/docbook/smbdotconf/security/restrictanonymous.xml new file mode 100644 index 0000000000..4b09b7d2bc --- /dev/null +++ b/docs/docbook/smbdotconf/security/restrictanonymous.xml @@ -0,0 +1,10 @@ + + restrict anonymous (G) + This is a integer parameter, and + mirrors as much as possible the functinality the + RestrictAnonymous + registry key does on NT/Win2k. + + Default: restrict anonymous = 0 + + diff --git a/docs/docbook/smbdotconf/security/root.xml b/docs/docbook/smbdotconf/security/root.xml new file mode 100644 index 0000000000..f69c1a1ae1 --- /dev/null +++ b/docs/docbook/smbdotconf/security/root.xml @@ -0,0 +1,6 @@ + + root (G) + Synonym for + root directory". + + diff --git a/docs/docbook/smbdotconf/security/rootdir.xml b/docs/docbook/smbdotconf/security/rootdir.xml new file mode 100644 index 0000000000..1f543aed6a --- /dev/null +++ b/docs/docbook/smbdotconf/security/rootdir.xml @@ -0,0 +1,6 @@ + + root dir (G) + Synonym for + root directory". + + diff --git a/docs/docbook/smbdotconf/security/rootdirectory.xml b/docs/docbook/smbdotconf/security/rootdirectory.xml new file mode 100644 index 0000000000..9efc11e3c6 --- /dev/null +++ b/docs/docbook/smbdotconf/security/rootdirectory.xml @@ -0,0 +1,28 @@ + + root directory (G) + The server will chroot() (i.e. + Change its root directory) to this directory on startup. This is + not strictly necessary for secure operation. Even without it the + server will deny access to files not in one of the service entries. + It may also check for, and deny access to, soft links to other + parts of the filesystem, or attempts to use ".." in file names + to access other directories (depending on the setting of the wide links + parameter). + + Adding a root directory entry other + than "/" adds an extra level of security, but at a price. It + absolutely ensures that no access is given to files not in the + sub-tree specified in the root directory + option, including some files needed for + complete operation of the server. To maintain full operability + of the server you will need to mirror some system files + into the root directory tree. In particular + you will need to mirror /etc/passwd (or a + subset of it), and any binaries or configuration files needed for + printing (if required). The set of files that must be mirrored is + operating system dependent. + + Default: root directory = / + Example: root directory = /homes/smb + + diff --git a/docs/docbook/smbdotconf/security/security.xml b/docs/docbook/smbdotconf/security/security.xml new file mode 100644 index 0000000000..8e97d8721f --- /dev/null +++ b/docs/docbook/smbdotconf/security/security.xml @@ -0,0 +1,237 @@ + + security (G) + This option affects how clients respond to + Samba and is one of the most important settings in the + smb.conf file. + + The option sets the "security mode bit" in replies to + protocol negotiations with smbd + 8 to turn share level security on or off. Clients decide + based on this bit whether (and how) to transfer user and password + information to the server. + + + The default is security = user, as this is + the most common setting needed when talking to Windows 98 and + Windows NT. + + The alternatives are security = share, + security = server or security = domain + . + + In versions of Samba prior to 2.0.0, the default was + security = share mainly because that was + the only option at one stage. + + There is a bug in WfWg that has relevance to this + setting. When in user or server level security a WfWg client + will totally ignore the password you type in the "connect + drive" dialog box. This makes it very difficult (if not impossible) + to connect to a Samba service as anyone except the user that + you are logged into WfWg as. + + If your PCs use usernames that are the same as their + usernames on the UNIX machine then you will want to use + security = user. If you mostly use usernames + that don't exist on the UNIX box then use security = + share. + + You should also use security = share if you + want to mainly setup shares without a password (guest shares). This + is commonly used for a shared printer server. It is more difficult + to setup guest shares with security = user, see + the map to guest + parameter for details. + + It is possible to use smbd in a + hybrid mode where it is offers both user and share + level security under different + NetBIOS aliases. + + The different settings will now be explained. + + + SECURITY = SHARE + + + When clients connect to a share level security server they + need not log onto the server with a valid username and password before + attempting to connect to a shared resource (although modern clients + such as Windows 95/98 and Windows NT will send a logon request with + a username but no password when talking to a security = share + server). Instead, the clients send authentication information + (passwords) on a per-share basis, at the time they attempt to connect + to that share. + + Note that smbd ALWAYS + uses a valid UNIX user to act on behalf of the client, even in + security = share level security. + + As clients are not required to send a username to the server + in share level security, smbd uses several + techniques to determine the correct UNIX user to use on behalf + of the client. + + A list of possible UNIX usernames to match with the given + client password is constructed using the following methods : + + + If the guest + only parameter is set, then all the other + stages are missed and only the + guest account username is checked. + + + Is a username is sent with the share connection + request, then this username (after mapping - see username map), + is added as a potential username. + + If the client did a previous logon + request (the SessionSetup SMB call) then the + username sent in this SMB will be added as a potential username. + + + The name of the service the client requested is + added as a potential username. + + The NetBIOS name of the client is added to + the list as a potential username. + + Any users on the + user list are added as potential usernames. + + + + If the guest only parameter is + not set, then this list is then tried with the supplied password. + The first user for whom the password matches will be used as the + UNIX user. + + If the guest only parameter is + set, or no username can be determined then if the share is marked + as available to the guest account, then this + guest user will be used, otherwise access is denied. + + Note that it can be very confusing + in share-level security as to which UNIX username will eventually + be used in granting access. + + See also the section + NOTE ABOUT USERNAME/PASSWORD VALIDATION. + + SECURITY = USER + + + This is the default security setting in Samba 3.0. + With user-level security a client must first "log-on" with a + valid username and password (which can be mapped using the username map + parameter). Encrypted passwords (see the + encrypted passwords parameter) can also + be used in this security mode. Parameters such as + user and + guest only if set are then applied and + may change the UNIX user to use on this connection, but only after + the user has been successfully authenticated. + + Note that the name of the resource being + requested is not sent to the server until after + the server has successfully authenticated the client. This is why + guest shares don't work in user level security without allowing + the server to automatically map unknown users into the guest account. + See the map to guest + parameter for details on doing this. + + See also the section + NOTE ABOUT USERNAME/PASSWORD VALIDATION. + + SECURITY = DOMAIN + + + + This mode will only work correctly if net + 8 has been used to add this + machine into a Windows NT Domain. It expects the encrypted passwords + parameter to be set to yes. In this + mode Samba will try to validate the username/password by passing + it to a Windows NT Primary or Backup Domain Controller, in exactly + the same way that a Windows NT Server would do. + + Note that a valid UNIX user must still + exist as well as the account on the Domain Controller to allow + Samba to have a valid UNIX account to map file access to. + + Note that from the client's point + of view security = domain is the same as security = user + . It only affects how the server deals with the authentication, + it does not in any way affect what the client sees. + + Note that the name of the resource being + requested is not sent to the server until after + the server has successfully authenticated the client. This is why + guest shares don't work in user level security without allowing + the server to automatically map unknown users into the guest account. + See the map to guest + parameter for details on doing this. + + See also the section + NOTE ABOUT USERNAME/PASSWORD VALIDATION. + + See also the password + server parameter and the encrypted passwords + parameter. + + SECURITY = SERVER + + + In this mode Samba will try to validate the username/password + by passing it to another SMB server, such as an NT box. If this + fails it will revert to security = + user. It expects the encrypted passwords + parameter to be set to + yes, unless the remote server + does not support them. However note + that if encrypted passwords have been negotiated then Samba cannot + revert back to checking the UNIX password file, it must have a valid + smbpasswd file to check users against. See the + documentation file in the docs/ directory + ENCRYPTION.txt for details on how to set this + up. + + Note this mode of operation + has significant pitfalls, due to the fact that is + activly initiates a man-in-the-middle attack on the + remote SMB server. In particular, this mode of + operation can cause significant resource consuption on + the PDC, as it must maintain an active connection for + the duration of the user's session. Furthermore, if + this connection is lost, there is no way to + reestablish it, and futher authenticaions to the Samba + server may fail. (From a single client, till it + disconnects). + + Note that from the client's point of + view security = server is the same as + security = user. It only affects how the server deals + with the authentication, it does not in any way affect what the + client sees. + + Note that the name of the resource being + requested is not sent to the server until after + the server has successfully authenticated the client. This is why + guest shares don't work in user level security without allowing + the server to automatically map unknown users into the guest account. + See the map to guest + parameter for details on doing this. + + See also the section + NOTE ABOUT USERNAME/PASSWORD VALIDATION. + + See also the password + server parameter and the encrypted passwords + parameter. + + Default: security = USER + Example: security = DOMAIN + + + diff --git a/docs/docbook/smbdotconf/security/securitymask.xml b/docs/docbook/smbdotconf/security/securitymask.xml new file mode 100644 index 0000000000..9ed0adcbf4 --- /dev/null +++ b/docs/docbook/smbdotconf/security/securitymask.xml @@ -0,0 +1,33 @@ + + security mask (S) + This parameter controls what UNIX permission + bits can be modified when a Windows NT client is manipulating + the UNIX permission on a file using the native NT security + dialog box. + + This parameter is applied as a mask (AND'ed with) to + the changed permission bits, thus preventing any bits not in + this mask from being modified. Essentially, zero bits in this + mask may be treated as a set of bits the user is not allowed + to change. + + If not set explicitly this parameter is 0777, allowing + a user to modify all the user/group/world permissions on a file. + + + Note that users who can access the + Samba server through other means can easily bypass this + restriction, so it is primarily useful for standalone + "appliance" systems. Administrators of most normal systems will + probably want to leave it set to 0777. + + See also the + force directory security mode, + directory + security mask, + force security mode parameters. + + Default: security mask = 0777 + Example: security mask = 0770 + + diff --git a/docs/docbook/smbdotconf/security/smbpasswdfile.xml b/docs/docbook/smbdotconf/security/smbpasswdfile.xml new file mode 100644 index 0000000000..2efbd12169 --- /dev/null +++ b/docs/docbook/smbdotconf/security/smbpasswdfile.xml @@ -0,0 +1,13 @@ + + smb passwd file (G) + This option sets the path to the encrypted + smbpasswd file. By default the path to the smbpasswd file + is compiled into Samba. + + Default: smb passwd file = ${prefix}/private/smbpasswd + + + Example: smb passwd file = /etc/samba/smbpasswd + + + diff --git a/docs/docbook/smbdotconf/security/unixpasswordsync.xml b/docs/docbook/smbdotconf/security/unixpasswordsync.xml new file mode 100644 index 0000000000..41c6d983d0 --- /dev/null +++ b/docs/docbook/smbdotconf/security/unixpasswordsync.xml @@ -0,0 +1,18 @@ + + unix password sync (G) + This boolean parameter controls whether Samba + attempts to synchronize the UNIX password with the SMB password + when the encrypted SMB password in the smbpasswd file is changed. + If this is set to yes the program specified in the passwd + programparameter is called AS ROOT - + to allow the new UNIX password to be set without access to the + old UNIX password (as the SMB password change code has no + access to the old password cleartext, only the new). + + See also passwd + program, + passwd chat. + + Default: unix password sync = no + + diff --git a/docs/docbook/smbdotconf/security/updateencrypted.xml b/docs/docbook/smbdotconf/security/updateencrypted.xml new file mode 100644 index 0000000000..45c66e0de2 --- /dev/null +++ b/docs/docbook/smbdotconf/security/updateencrypted.xml @@ -0,0 +1,28 @@ + + update encrypted (G) + This boolean parameter allows a user logging + on with a plaintext password to have their encrypted (hashed) + password in the smbpasswd file to be updated automatically as + they log on. This option allows a site to migrate from plaintext + password authentication (users authenticate with plaintext + password over the wire, and are checked against a UNIX account + database) to encrypted password authentication (the SMB + challenge/response authentication mechanism) without forcing + all users to re-enter their passwords via smbpasswd at the time the + change is made. This is a convenience option to allow the change over + to encrypted passwords to be made over a longer period. Once all users + have encrypted representations of their passwords in the smbpasswd + file this parameter should be set to no. + + In order for this parameter to work correctly the encrypt passwords + parameter must be set to no when + this parameter is set to yes. + + Note that even when this parameter is set a user + authenticating to smbd must still enter a valid + password in order to connect correctly, and to update their hashed + (smbpasswd) passwords. + + Default: update encrypted = no + + diff --git a/docs/docbook/smbdotconf/security/user.xml b/docs/docbook/smbdotconf/security/user.xml new file mode 100644 index 0000000000..9c0502061b --- /dev/null +++ b/docs/docbook/smbdotconf/security/user.xml @@ -0,0 +1,6 @@ + + user (S) + Synonym for + username. + + diff --git a/docs/docbook/smbdotconf/security/username.xml b/docs/docbook/smbdotconf/security/username.xml new file mode 100644 index 0000000000..779f24170b --- /dev/null +++ b/docs/docbook/smbdotconf/security/username.xml @@ -0,0 +1,62 @@ + + username (S) + Multiple users may be specified in a comma-delimited + list, in which case the supplied password will be tested against + each username in turn (left to right). + + The username line is needed only when + the PC is unable to supply its own username. This is the case + for the COREPLUS protocol or where your users have different WfWg + usernames to UNIX usernames. In both these cases you may also be + better using the \\server\share%user syntax instead. + + The username line is not a great + solution in many cases as it means Samba will try to validate + the supplied password against each of the usernames in the + username line in turn. This is slow and + a bad idea for lots of users in case of duplicate passwords. + You may get timeouts or security breaches using this parameter + unwisely. + + Samba relies on the underlying UNIX security. This + parameter does not restrict who can login, it just offers hints + to the Samba server as to what usernames might correspond to the + supplied password. Users can login as whoever they please and + they will be able to do no more damage than if they started a + telnet session. The daemon runs as the user that they log in as, + so they cannot do anything that user cannot do. + + To restrict a service to a particular set of users you + can use the valid users + parameter. + + If any of the usernames begin with a '@' then the name + will be looked up first in the NIS netgroups list (if Samba + is compiled with netgroup support), followed by a lookup in + the UNIX groups database and will expand to a list of all users + in the group of that name. + + If any of the usernames begin with a '+' then the name + will be looked up only in the UNIX groups database and will + expand to a list of all users in the group of that name. + + If any of the usernames begin with a '&' then the name + will be looked up only in the NIS netgroups database (if Samba + is compiled with netgroup support) and will expand to a list + of all users in the netgroup group of that name. + + Note that searching though a groups database can take + quite some time, and some clients may time out during the + search. + + See the section NOTE ABOUT + USERNAME/PASSWORD VALIDATION for more information on how + this parameter determines access to the services. + + Default: The guest account if a guest service, + else <empty string>. + + Examples:username = fred, mary, jack, jane, + @users, @pcgroup + + diff --git a/docs/docbook/smbdotconf/security/usernamelevel.xml b/docs/docbook/smbdotconf/security/usernamelevel.xml new file mode 100644 index 0000000000..a4deff3bf9 --- /dev/null +++ b/docs/docbook/smbdotconf/security/usernamelevel.xml @@ -0,0 +1,20 @@ + + username level (G) + This option helps Samba to try and 'guess' at + the real UNIX username, as many DOS clients send an all-uppercase + username. By default Samba tries all lowercase, followed by the + username with the first letter capitalized, and fails if the + username is not found on the UNIX machine. + + If this parameter is set to non-zero the behavior changes. + This parameter is a number that specifies the number of uppercase + combinations to try while trying to determine the UNIX user name. The + higher the number the more combinations will be tried, but the slower + the discovery of usernames will be. Use this parameter when you have + strange usernames on your UNIX machine, such as AstrangeUser + . + + Default: username level = 0 + Example: username level = 5 + + diff --git a/docs/docbook/smbdotconf/security/usernamemap.xml b/docs/docbook/smbdotconf/security/usernamemap.xml new file mode 100644 index 0000000000..37ee72c235 --- /dev/null +++ b/docs/docbook/smbdotconf/security/usernamemap.xml @@ -0,0 +1,90 @@ + + username map (G) + This option allows you to specify a file containing + a mapping of usernames from the clients to the server. This can be + used for several purposes. The most common is to map usernames + that users use on DOS or Windows machines to those that the UNIX + box uses. The other is to map multiple users to a single username + so that they can more easily share files. + + The map file is parsed line by line. Each line should + contain a single UNIX username on the left then a '=' followed + by a list of usernames on the right. The list of usernames on the + right may contain names of the form @group in which case they + will match any UNIX username in that group. The special client + name '*' is a wildcard and matches any name. Each line of the + map file may be up to 1023 characters long. + + The file is processed on each line by taking the + supplied username and comparing it with each username on the right + hand side of the '=' signs. If the supplied name matches any of + the names on the right hand side then it is replaced with the name + on the left. Processing then continues with the next line. + + If any line begins with a '#' or a ';' then it is + ignored + + If any line begins with an '!' then the processing + will stop after that line if a mapping was done by the line. + Otherwise mapping continues with every line being processed. + Using '!' is most useful when you have a wildcard mapping line + later in the file. + + For example to map from the name admin + or administrator to the UNIX name + root you would use: + + root = admin administrator + + Or to map anyone in the UNIX group system + to the UNIX name sys you would use: + + sys = @system + + You can have as many mappings as you like in a username + map file. + + + If your system supports the NIS NETGROUP option then + the netgroup database is checked before the /etc/group + database for matching groups. + + You can map Windows usernames that have spaces in them + by using double quotes around the name. For example: + + tridge = "Andrew Tridgell" + + would map the windows username "Andrew Tridgell" to the + unix username "tridge". + + The following example would map mary and fred to the + unix user sys, and map the rest to guest. Note the use of the + '!' to tell Samba to stop processing if it gets a match on + that line. + + +!sys = mary fred +guest = * + + + Note that the remapping is applied to all occurrences + of usernames. Thus if you connect to \\server\fred and + fred is remapped to mary then you + will actually be connecting to \\server\mary and will need to + supply a password suitable for mary not + fred. The only exception to this is the + username passed to the + password server (if you have one). The password + server will receive whatever username the client supplies without + modification. + + Also note that no reverse mapping is done. The main effect + this has is with printing. Users who have been mapped may have + trouble deleting print jobs as PrintManager under WfWg will think + they don't own the print job. + + Default: no username map + Example: username map = /usr/local/samba/lib/users.map + + + diff --git a/docs/docbook/smbdotconf/security/users.xml b/docs/docbook/smbdotconf/security/users.xml new file mode 100644 index 0000000000..e78d259f62 --- /dev/null +++ b/docs/docbook/smbdotconf/security/users.xml @@ -0,0 +1,6 @@ + + users (S) + Synonym for + username. + + diff --git a/docs/docbook/smbdotconf/security/validusers.xml b/docs/docbook/smbdotconf/security/validusers.xml new file mode 100644 index 0000000000..5155a5ef34 --- /dev/null +++ b/docs/docbook/smbdotconf/security/validusers.xml @@ -0,0 +1,23 @@ + + valid users (S) + This is a list of users that should be allowed + to login to this service. Names starting with '@', '+' and '&' + are interpreted using the same rules as described in the + invalid users parameter. + + If this is empty (the default) then any user can login. + If a username is in both this list and the invalid + users list then access is denied for that user. + + The current servicename is substituted for %S + . This is useful in the [homes] section. + + See also invalid users + + + Default: No valid users list (anyone can login) + + + Example: valid users = greg, @pcusers + + diff --git a/docs/docbook/smbdotconf/security/writable.xml b/docs/docbook/smbdotconf/security/writable.xml new file mode 100644 index 0000000000..66ba44cc44 --- /dev/null +++ b/docs/docbook/smbdotconf/security/writable.xml @@ -0,0 +1,6 @@ + + writable (S) + Synonym for + writeable for people who can't spell :-). + + diff --git a/docs/docbook/smbdotconf/security/writeable.xml b/docs/docbook/smbdotconf/security/writeable.xml new file mode 100644 index 0000000000..b963410374 --- /dev/null +++ b/docs/docbook/smbdotconf/security/writeable.xml @@ -0,0 +1,6 @@ + + writeable (S) + Inverted synonym for + read only. + + diff --git a/docs/docbook/smbdotconf/security/writelist.xml b/docs/docbook/smbdotconf/security/writelist.xml new file mode 100644 index 0000000000..76ee56c93a --- /dev/null +++ b/docs/docbook/smbdotconf/security/writelist.xml @@ -0,0 +1,21 @@ + + write list (S) + This is a list of users that are given read-write + access to a service. If the connecting user is in this list then + they will be given write access, no matter what the read only + option is set to. The list can include group names using the + @group syntax. + + Note that if a user is in both the read list and the + write list then they will be given write access. + + See also the read list + option. + + Default: write list = <empty string> + + + Example: write list = admin, root, @staff + + + diff --git a/docs/docbook/smbdotconf/security/writeok.xml b/docs/docbook/smbdotconf/security/writeok.xml new file mode 100644 index 0000000000..103c2be993 --- /dev/null +++ b/docs/docbook/smbdotconf/security/writeok.xml @@ -0,0 +1,6 @@ + + write ok (S) + Inverted synonym for + read only. + + diff --git a/docs/docbook/smbdotconf/smb.conf.5.xml b/docs/docbook/smbdotconf/smb.conf.5.xml new file mode 100644 index 0000000000..e37add4206 --- /dev/null +++ b/docs/docbook/smbdotconf/smb.conf.5.xml @@ -0,0 +1,685 @@ + + %globalentities; +]> + + + + smb.conf + 5 + + + + + smb.conf + The configuration file for the Samba suite + + + + SYNOPSIS + + The smb.conf file is a configuration + file for the Samba suite. smb.conf contains + runtime configuration information for the Samba programs. The smb.conf file + is designed to be configured and administered by the swat + 8 program. The complete + description of the file format and possible parameters held within + are here for reference purposes. + + + FILE FORMAT + + The file consists of sections and parameters. A section + begins with the name of the section in square brackets and continues + until the next section begins. Sections contain parameters of the + form + + name = value + + + The file is line-based - that is, each newline-terminated + line represents either a comment, a section name or a parameter. + + Section and parameter names are not case sensitive. + + Only the first equals sign in a parameter is significant. + Whitespace before or after the first equals sign is discarded. + Leading, trailing and internal whitespace in section and parameter + names is irrelevant. Leading and trailing whitespace in a parameter + value is discarded. Internal whitespace within a parameter value + is retained verbatim. + + Any line beginning with a semicolon (';') or a hash ('#') + character is ignored, as are lines containing only whitespace. + + Any line ending in a '\' is continued + on the next line in the customary UNIX fashion. + + The values following the equals sign in parameters are all + either a string (no quotes needed) or a boolean, which may be given + as yes/no, 0/1 or true/false. Case is not significant in boolean + values, but is preserved in string values. Some items such as + create modes are numeric. + + + + SECTION DESCRIPTIONS + + Each section in the configuration file (except for the + [global] section) describes a shared resource (known + as a "share"). The section name is the name of the + shared resource and the parameters within the section define + the shares attributes. + + There are three special sections, [global], + [homes] and [printers], which are + described under special sections. The + following notes apply to ordinary section descriptions. + + A share consists of a directory to which access is being + given plus a description of the access rights which are granted + to the user of the service. Some housekeeping options are + also specifiable. + + Sections are either file share services (used by the + client as an extension of their native file systems) or + printable services (used by the client to access print services + on the host running the server). + + Sections may be designated guest services, + in which case no password is required to access them. A specified + UNIX guest account is used to define access + privileges in this case. + + Sections other than guest services will require a password + to access them. The client provides the username. As older clients + only provide passwords and not usernames, you may specify a list + of usernames to check against the password using the "user =" + option in the share definition. For modern clients such as + Windows 95/98/ME/NT/2000, this should not be necessary. + + Note that the access rights granted by the server are + masked by the access rights granted to the specified or guest + UNIX user by the host system. The server does not grant more + access than the host system grants. + + The following sample section defines a file space share. + The user has write access to the path /home/bar. + The share is accessed via the share name "foo": + + + +[foo] + path = /home/bar + read only = no + + + + The following sample section defines a printable share. + The share is readonly, but printable. That is, the only write + access permitted is via calls to open, write to and close a + spool file. The guest ok parameter means + access will be permitted as the default guest user (specified + elsewhere): + + + +[aprinter] + path = /usr/spool/public + read only = yes + printable = yes + guest ok = yes + + + + + + SPECIAL SECTIONS + + + The [global] section + + parameters in this section apply to the server + as a whole, or are defaults for sections which do not + specifically define certain items. See the notes + under PARAMETERS for more information. + + + + The [homes] section + + If a section called homes is included in the + configuration file, services connecting clients to their + home directories can be created on the fly by the server. + + When the connection request is made, the existing + sections are scanned. If a match is found, it is used. If no + match is found, the requested section name is treated as a + user name and looked up in the local password file. If the + name exists and the correct password has been given, a share is + created by cloning the [homes] section. + + Some modifications are then made to the newly + created share: + + + The share name is changed from homes to + the located username. + + If no path was given, the path is set to + the user's home directory. + + + If you decide to use a path = line + in your [homes] section then you may find it useful + to use the %S macro. For example : + + path = /data/pchome/%S + + would be useful if you have different home directories + for your PCs than for UNIX access. + + This is a fast and simple way to give a large number + of clients access to their home directories with a minimum + of fuss. + + A similar process occurs if the requested section + name is "homes", except that the share name is not + changed to that of the requesting user. This method of using + the [homes] section works well if different users share + a client PC. + + The [homes] section can specify all the parameters + a normal service section can specify, though some make more sense + than others. The following is a typical and suitable [homes] + section: + + + +[homes] + read only = no + + + + An important point is that if guest access is specified + in the [homes] section, all home directories will be + visible to all clients without a password. + In the very unlikely event that this is actually desirable, it + would be wise to also specify read only + access. + + Note that the browseable flag for + auto home directories will be inherited from the global browseable + flag, not the [homes] browseable flag. This is useful as + it means setting browseable = no in + the [homes] section will hide the [homes] share but make + any auto home directories visible. + + + + The [printers] section + + This section works like [homes], + but for printers. + + If a [printers] section occurs in the + configuration file, users are able to connect to any printer + specified in the local host's printcap file. + + When a connection request is made, the existing sections + are scanned. If a match is found, it is used. If no match is found, + but a [homes] section exists, it is used as described + above. Otherwise, the requested section name is treated as a + printer name and the appropriate printcap file is scanned to see + if the requested section name is a valid printer share name. If + a match is found, a new printer share is created by cloning + the [printers] section. + + A few modifications are then made to the newly created + share: + + + The share name is set to the located printer + name + + If no printer name was given, the printer name + is set to the located printer name + + If the share does not permit guest access and + no username was given, the username is set to the located + printer name. + + + Note that the [printers] service MUST be + printable - if you specify otherwise, the server will refuse + to load the configuration file. + + Typically the path specified would be that of a + world-writeable spool directory with the sticky bit set on + it. A typical [printers] entry would look like + this: + + +[printers] + path = /usr/spool/public + guest ok = yes + printable = yes + + + All aliases given for a printer in the printcap file + are legitimate printer names as far as the server is concerned. + If your printing subsystem doesn't work like that, you will have + to set up a pseudo-printcap. This is a file consisting of one or + more lines like this: + + + +alias|alias|alias|alias... + + + + Each alias should be an acceptable printer name for + your printing subsystem. In the [global] section, specify + the new file as your printcap. The server will then only recognize + names found in your pseudo-printcap, which of course can contain + whatever aliases you like. The same technique could be used + simply to limit access to a subset of your local printers. + + An alias, by the way, is defined as any component of the + first entry of a printcap record. Records are separated by newlines, + components (if there are more than one) are separated by vertical + bar symbols ('|'). + + NOTE: On SYSV systems which use lpstat to determine what + printers are defined on the system you may be able to use + "printcap name = lpstat" to automatically obtain a list + of printers. See the "printcap name" option + for more details. + + + + + PARAMETERS + + parameters define the specific attributes of sections. + + Some parameters are specific to the [global] section + (e.g., security). Some parameters are usable + in all sections (e.g., create mode). All others + are permissible only in normal sections. For the purposes of the + following descriptions the [homes] and [printers] + sections will be considered normal. The letter G + in parentheses indicates that a parameter is specific to the + [global] section. The letter S + indicates that a parameter can be specified in a service specific + section. Note that all S parameters can also be specified in + the [global] section - in which case they will define + the default behavior for all services. + + parameters are arranged here in alphabetical order - this may + not create best bedfellows, but at least you can find them! Where + there are synonyms, the preferred synonym is described, others refer + to the preferred synonym. + + + + VARIABLE SUBSTITUTIONS + + Many of the strings that are settable in the config file + can take substitutions. For example the option "path = + /tmp/%u" would be interpreted as "path = + /tmp/john" if the user connected with the username john. + + These substitutions are mostly noted in the descriptions below, + but there are some general substitutions which apply whenever they + might be relevant. These are: + + + + %U + session user name (the user name that the client + wanted, not necessarily the same as the one they got). + + + + %G + primary group name of %U. + + + + %h + the Internet hostname that Samba is running + on. + + + + %m + the NetBIOS name of the client machine + (very useful). + + + + %L + the NetBIOS name of the server. This allows you + to change your config based on what the client calls you. Your + server can have a "dual personality". + + Note that this parameter is not available when Samba listens + on port 445, as clients no longer send this information + + + + + + %M + the Internet name of the client machine. + + + + + %R + the selected protocol level after + protocol negotiation. It can be one of CORE, COREPLUS, + LANMAN1, LANMAN2 or NT1. + + + + %d + The process id of the current server + process. + + + + %a + the architecture of the remote + machine. Only some are recognized, and those may not be + 100% reliable. It currently recognizes Samba, WfWg, Win95, + WinNT and Win2k. Anything else will be known as + "UNKNOWN". If it gets it wrong then sending a level + 3 log to samba@samba.org + should allow it to be fixed. + + + + %I + The IP address of the client machine. + + + + + %T + the current date and time. + + + + %D + Name of the domain or workgroup of the current user. + + + + %$(envvar) + The value of the environment variable + envar. + + + + The following substitutes apply only to some configuration options(only those + that are used when a connection has been established): + + + + %S + the name of the current service, if any. + + + + + %P + the root directory of the current service, + if any. + + + + %u + user name of the current service, if any. + + + + + %g + primary group name of %u. + + + + %H + the home directory of the user given + by %u. + + + + %N + the name of your NIS home directory server. + This is obtained from your NIS auto.map entry. If you have + not compiled Samba with the --with-automount + option then this value will be the same as %L. + + + + + %p + the path of the service's home directory, + obtained from your NIS auto.map entry. The NIS auto.map entry + is split up as "%N:%p". + + + + There are some quite creative things that can be done + with these substitutions and other smb.conf options. + + + + NAME MANGLING + + Samba supports "name mangling" so that DOS and + Windows clients can use files that don't conform to the 8.3 format. + It can also be set to adjust the case of 8.3 format filenames. + + There are several options that control the way mangling is + performed, and they are grouped here rather than listed separately. + For the defaults look at the output of the testparm program. + + All of these options can be set separately for each service + (or globally, of course). + + The options are: + + + + + mangle case = yes/no + controls if names that have characters that + aren't of the "default" case are mangled. For example, + if this is yes then a name like "Mail" would be mangled. + Default no. + + + + case sensitive = yes/no + controls whether filenames are case sensitive. If + they aren't then Samba must do a filename search and match on passed + names. Default no. + + + + default case = upper/lower + controls what the default case is for new + filenames. Default lower. + + + + preserve case = yes/no + controls if new files are created with the + case that the client passes, or if they are forced to be the + "default" case. Default yes. + + + + + short preserve case = yes/no + controls if new files which conform to 8.3 syntax, + that is all in upper case and of suitable length, are created + upper case, or if they are forced to be the "default" + case. This option can be use with "preserve case = yes" + to permit long filenames to retain their case, while short names + are lowercased. Default yes. + + + + By default, Samba 3.0 has the same semantics as a Windows + NT server, in that it is case insensitive but case preserving. + + + + + NOTE ABOUT USERNAME/PASSWORD VALIDATION + + There are a number of ways in which a user can connect + to a service. The server uses the following steps in determining + if it will allow a connection to a specified service. If all the + steps fail, then the connection request is rejected. However, if one of the + steps succeeds, then the following steps are not checked. + + If the service is marked "guest only = yes" and the + server is running with share-level security ("security = share") + then steps 1 to 5 are skipped. + + + + If the client has passed a username/password + pair and that username/password pair is validated by the UNIX + system's password programs then the connection is made as that + username. Note that this includes the + \\server\service%username method of passing + a username. + + If the client has previously registered a username + with the system and now supplies a correct password for that + username then the connection is allowed. + + The client's NetBIOS name and any previously + used user names are checked against the supplied password, if + they match then the connection is allowed as the corresponding + user. + + If the client has previously validated a + username/password pair with the server and the client has passed + the validation token then that username is used. + + If a "user = " field is given in the + smb.conf file for the service and the client + has supplied a password, and that password matches (according to + the UNIX system's password checking) with one of the usernames + from the "user =" field then the connection is made as + the username in the "user =" line. If one + of the username in the "user =" list begins with a + '@' then that name expands to a list of names in + the group of the same name. + + If the service is a guest service then a + connection is made as the username given in the "guest + account =" for the service, irrespective of the + supplied password. + + + + + + COMPLETE LIST OF GLOBAL PARAMETERS + + Here is a list of all global parameters. See the section of + each parameter for details. Note that some are synonyms. + + + + + + + COMPLETE LIST OF SERVICE PARAMETERS + + Here is a list of all service parameters. See the section on + each parameter for details. Note that some are synonyms. + + + + + + + EXPLANATION OF EACH PARAMETER + + + + + + + WARNINGS + + Although the configuration file permits service names + to contain spaces, your client software may not. Spaces will + be ignored in comparisons anyway, so it shouldn't be a + problem - but be aware of the possibility. + + On a similar note, many clients - especially DOS clients - + limit service names to eight characters. smbd + 8 has no such limitation, but attempts to connect from such + clients will fail if they truncate the service names. For this reason + you should probably keep your service names down to eight characters + in length. + + Use of the [homes] and [printers] special sections make life + for an administrator easy, but the various combinations of default + attributes can be tricky. Take extreme care when designing these + sections. In particular, ensure that the permissions on spool + directories are correct. + + + + VERSION + + This man page is correct for version 3.0 of the Samba suite. + + + + SEE ALSO + + samba + 7, smbpasswd + 8, swat + 8, smbd + 8, nmbd + 8, smbclient + 1, nmblookup + 1, testparm + 1, testprns + 1. + + + + AUTHOR + + The original Samba software and related utilities + were created by Andrew Tridgell. Samba is now developed + by the Samba Team as an Open Source project similar + to the way the Linux kernel is developed. + + The original Samba man pages were written by Karl Auer. + The man page sources were converted to YODL format (another + excellent piece of Open Source software, available at + ftp://ftp.icce.rug.nl/pub/unix/) and updated for the Samba 2.0 + release by Jeremy Allison. The conversion to DocBook for + Samba 2.2 was done by Gerald Carter. The conversion to DocBook XML 4.2 + for Samba 3.0 was done by Alexander Bokovoy. + + + diff --git a/docs/docbook/smbdotconf/smbconf.dtd b/docs/docbook/smbdotconf/smbconf.dtd new file mode 100644 index 0000000000..00340a7db9 --- /dev/null +++ b/docs/docbook/smbdotconf/smbconf.dtd @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/docbook/smbdotconf/split-original-smb.conf.xsl b/docs/docbook/smbdotconf/split-original-smb.conf.xsl new file mode 100644 index 0000000000..7a6a2b920a --- /dev/null +++ b/docs/docbook/smbdotconf/split-original-smb.conf.xsl @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .xml + + + Writing + + for + + + ( + + ) + + + + + + + + + &smb. + + ; + + + + + + + + + + + diff --git a/docs/docbook/smbdotconf/tuning/blocksize.xml b/docs/docbook/smbdotconf/tuning/blocksize.xml new file mode 100644 index 0000000000..da42ca9ece --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/blocksize.xml @@ -0,0 +1,19 @@ + + block size (S) + This parameter controls the behavior of smbd + 8 when reporting disk free + sizes. By default, this reports a disk block size of 1024 bytes. + + + Changing this parameter may have some effect on the + efficiency of client writes, this is not yet confirmed. This + parameter was added to allow advanced administrators to change + it (usually to a higher value) and test the effect it has on + client write performance without re-compiling the code. As this + is an experimental option it may be removed in a future release. + + + Changing this option does not change the disk free reporting + size, just the block size unit reported to the client. + + diff --git a/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml b/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml new file mode 100644 index 0000000000..18c8b9a176 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/changenotifytimeout.xml @@ -0,0 +1,15 @@ + + change notify timeout (G) + This SMB allows a client to tell a server to + "watch" a particular directory for any changes and only reply to + the SMB request when a change has occurred. Such constant scanning of + a directory is expensive under UNIX, hence an smbd + 8 daemon only performs such a scan + on each requested directory once every change notify + timeout seconds. + + Default: change notify timeout = 60 + Example: change notify timeout = 300 + + Would change the scan time to every 5 minutes. + diff --git a/docs/docbook/smbdotconf/tuning/deadtime.xml b/docs/docbook/smbdotconf/tuning/deadtime.xml new file mode 100644 index 0000000000..dbad06f25b --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/deadtime.xml @@ -0,0 +1,23 @@ + + deadtime (G) + The value of the parameter (a decimal integer) + represents the number of minutes of inactivity before a connection + is considered dead, and it is disconnected. The deadtime only takes + effect if the number of open files is zero. + + This is useful to stop a server's resources being + exhausted by a large number of inactive connections. + + Most clients have an auto-reconnect feature when a + connection is broken so in most cases this parameter should be + transparent to users. + + Using this parameter with a timeout of a few minutes + is recommended for most systems. + + A deadtime of zero indicates that no auto-disconnection + should be performed. + + Default: deadtime = 0 + Example: deadtime = 15 + diff --git a/docs/docbook/smbdotconf/tuning/getwdcache.xml b/docs/docbook/smbdotconf/tuning/getwdcache.xml new file mode 100644 index 0000000000..c797bad414 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/getwdcache.xml @@ -0,0 +1,11 @@ + + getwd cache (G) + This is a tuning option. When this is enabled a + caching algorithm will be used to reduce the time taken for getwd() + calls. This can have a significant impact on performance, especially + when the wide links + parameter is set to no. + + Default: getwd cache = yes + + diff --git a/docs/docbook/smbdotconf/tuning/hostnamelookups.xml b/docs/docbook/smbdotconf/tuning/hostnamelookups.xml new file mode 100644 index 0000000000..daad09da8b --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/hostnamelookups.xml @@ -0,0 +1,14 @@ + + hostname lookups (G) + Specifies whether samba should use (expensive) + hostname lookups or use the ip addresses instead. An example place + where hostname lookups are currently used is when checking + the hosts deny and hosts allow. + + + Default: hostname lookups = yes + + Example: hostname lookups = no + + + diff --git a/docs/docbook/smbdotconf/tuning/keepalive.xml b/docs/docbook/smbdotconf/tuning/keepalive.xml new file mode 100644 index 0000000000..746cda929e --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/keepalive.xml @@ -0,0 +1,16 @@ + + keepalive (G) + The value of the parameter (an integer) represents + the number of seconds between keepalive + packets. If this parameter is zero, no keepalive packets will be + sent. Keepalive packets, if sent, allow the server to tell whether + a client is still present and responding. + + Keepalives should, in general, not be needed if the socket + being used has the SO_KEEPALIVE attribute set on it (see socket options). + Basically you should only use this option if you strike difficulties. + + Default: keepalive = 300 + Example: keepalive = 600 + + diff --git a/docs/docbook/smbdotconf/tuning/maxconnections.xml b/docs/docbook/smbdotconf/tuning/maxconnections.xml new file mode 100644 index 0000000000..24af886b60 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/maxconnections.xml @@ -0,0 +1,16 @@ + + max connections (S) + This option allows the number of simultaneous + connections to a service to be limited. If max connections + is greater than 0 then connections will be refused if + this number of connections to the service are already open. A value + of zero mean an unlimited number of connections may be made. + + Record lock files are used to implement this feature. The + lock files will be stored in the directory specified by the lock directory + option. + + Default: max connections = 0 + Example: max connections = 10 + + diff --git a/docs/docbook/smbdotconf/tuning/maxdisksize.xml b/docs/docbook/smbdotconf/tuning/maxdisksize.xml new file mode 100644 index 0000000000..8aebe91902 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/maxdisksize.xml @@ -0,0 +1,24 @@ + + max disk size (G) + This option allows you to put an upper limit + on the apparent size of disks. If you set this option to 100 + then all shares will appear to be not larger than 100 MB in + size. + + Note that this option does not limit the amount of + data you can put on the disk. In the above case you could still + store much more than 100 MB on the disk, but if a client ever asks + for the amount of free disk space or the total disk size then the + result will be bounded by the amount specified in max + disk size. + + This option is primarily useful to work around bugs + in some pieces of software that can't handle very large disks, + particularly disks over 1GB in size. + + A max disk size of 0 means no limit. + + Default: max disk size = 0 + Example: max disk size = 1000 + + diff --git a/docs/docbook/smbdotconf/tuning/maxopenfiles.xml b/docs/docbook/smbdotconf/tuning/maxopenfiles.xml new file mode 100644 index 0000000000..85b76a3378 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/maxopenfiles.xml @@ -0,0 +1,16 @@ + + max open files (G) + This parameter limits the maximum number of + open files that one smbd + 8 file + serving process may have open for a client at any one time. The + default for this parameter is set very high (10,000) as Samba uses + only one bit per unopened file. + + The limit of the number of open files is usually set + by the UNIX per-process file descriptor limit rather than + this parameter so you should never need to touch this parameter. + + Default: max open files = 10000 + + diff --git a/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml b/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml new file mode 100644 index 0000000000..e46f0185ce --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/maxsmbdprocesses.xml @@ -0,0 +1,17 @@ + + max smbd processes (G) + This parameter limits the maximum number of + smbd(8) + processes concurrently running on a system and is intended + as a stopgap to prevent degrading service to clients in the event + that the server has insufficient resources to handle more than this + number of connections. Remember that under normal operating + conditions, each user will have an smbd + 8 associated with him or her + to handle connections to all shares from a given host. + + + Default: max smbd processes = 0 ## no limit + Example: max smbd processes = 1000 + + diff --git a/docs/docbook/smbdotconf/tuning/minprintspace.xml b/docs/docbook/smbdotconf/tuning/minprintspace.xml new file mode 100644 index 0000000000..acbb65fa41 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/minprintspace.xml @@ -0,0 +1,14 @@ + + min print space (S) + This sets the minimum amount of free disk + space that must be available before a user will be able to spool + a print job. It is specified in kilobytes. The default is 0, which + means a user can always spool a print job. + + See also the printing + parameter. + + Default: min print space = 0 + Example: min print space = 2000 + + diff --git a/docs/docbook/smbdotconf/tuning/namecachetimeout.xml b/docs/docbook/smbdotconf/tuning/namecachetimeout.xml new file mode 100644 index 0000000000..0500a75c8d --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/namecachetimeout.xml @@ -0,0 +1,12 @@ + + name cache timeout (G) + Specifies the number of seconds it takes before + entries in samba's hostname resolve cache time out. If + the timeout is set to 0. the caching is disabled. + + + + Default: name cache timeout = 660 + Example: name cache timeout = 0 + + diff --git a/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml b/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml new file mode 100644 index 0000000000..d60f179176 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/paranoidserversecurity.xml @@ -0,0 +1,16 @@ + + paranoid server security (G) + Some version of NT 4.x allow non-guest + users with a bad passowrd. When this option is enabled, samba will not + use a broken NT 4.x server as password server, but instead complain + to the logs and exit. + + + Disabling this option prevents Samba from making + this check, which involves deliberatly attempting a + bad logon to the remote server. + + Default: paranoid server security = yes + + + diff --git a/docs/docbook/smbdotconf/tuning/readsize.xml b/docs/docbook/smbdotconf/tuning/readsize.xml new file mode 100644 index 0000000000..59c6848c76 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/readsize.xml @@ -0,0 +1,25 @@ + + read size (G) + The option read size + affects the overlap of disk reads/writes with network reads/writes. + If the amount of data being transferred in several of the SMB + commands (currently SMBwrite, SMBwriteX and SMBreadbraw) is larger + than this value then the server begins writing the data before it + has received the whole packet from the network, or in the case of + SMBreadbraw, it begins writing to the network before all the data + has been read from disk. + + This overlapping works best when the speeds of disk and + network access are similar, having very little effect when the + speed of one is much greater than the other. + + The default value is 16384, but very little experimentation + has been done yet to determine the optimal value, and it is likely + that the best value will vary greatly between systems anyway. + A value over 65536 is pointless and will cause you to allocate + memory unnecessarily. + + Default: read size = 16384 + Example: read size = 8192 + + diff --git a/docs/docbook/smbdotconf/tuning/socketoptions.xml b/docs/docbook/smbdotconf/tuning/socketoptions.xml new file mode 100644 index 0000000000..3acc259083 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/socketoptions.xml @@ -0,0 +1,69 @@ + + socket options (G) + This option allows you to set socket options + to be used when talking with the client. + + Socket options are controls on the networking layer + of the operating systems which allow the connection to be + tuned. + + This option will typically be used to tune your Samba + server for optimal performance for your local network. There is + no way that Samba can know what the optimal parameters are for + your net, so you must experiment and choose them yourself. We + strongly suggest you read the appropriate documentation for your + operating system first (perhaps man setsockopt + will help). + + You may find that on some systems Samba will say + "Unknown socket option" when you supply an option. This means you + either incorrectly typed it or you need to add an include file + to includes.h for your OS. If the latter is the case please + send the patch to + samba@samba.org. + + Any of the supported socket options may be combined + in any way you like, as long as your OS allows it. + + This is the list of socket options currently settable + using this option: + + + SO_KEEPALIVE + SO_REUSEADDR + SO_BROADCAST + TCP_NODELAY + IPTOS_LOWDELAY + IPTOS_THROUGHPUT + SO_SNDBUF * + SO_RCVBUF * + SO_SNDLOWAT * + SO_RCVLOWAT * + + + Those marked with a '*' take an integer + argument. The others can optionally take a 1 or 0 argument to enable + or disable the option, by default they will be enabled if you + don't specify 1 or 0. + + To specify an argument use the syntax SOME_OPTION = VALUE + for example SO_SNDBUF = 8192. Note that you must + not have any spaces before or after the = sign. + + If you are on a local network then a sensible option + might be + socket options = IPTOS_LOWDELAY + + If you have a local network then you could try: + socket options = IPTOS_LOWDELAY TCP_NODELAY + + If you are on a wide area network then perhaps try + setting IPTOS_THROUGHPUT. + + Note that several of the options may cause your Samba + server to fail completely. Use these options with caution! + + Default: socket options = TCP_NODELAY + Example: socket options = IPTOS_LOWDELAY + + diff --git a/docs/docbook/smbdotconf/tuning/statcachesize.xml b/docs/docbook/smbdotconf/tuning/statcachesize.xml new file mode 100644 index 0000000000..fe7d3a7be2 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/statcachesize.xml @@ -0,0 +1,9 @@ + + stat cache size (G) + This parameter determines the number of + entries in the stat cache. You should + never need to change this parameter. + + Default: stat cache size = 50 + + diff --git a/docs/docbook/smbdotconf/tuning/strictallocate.xml b/docs/docbook/smbdotconf/tuning/strictallocate.xml new file mode 100644 index 0000000000..7b33ef3fc3 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/strictallocate.xml @@ -0,0 +1,21 @@ + + strict allocate (S) + This is a boolean that controls the handling of + disk space allocation in the server. When this is set to yes + the server will change from UNIX behaviour of not committing real + disk storage blocks when a file is extended to the Windows behaviour + of actually forcing the disk system to allocate real storage blocks + when a file is created or extended to be a given size. In UNIX + terminology this means that Samba will stop creating sparse files. + This can be slow on some systems. + + When strict allocate is no the server does sparse + disk block allocation when a file is extended. + + Setting this to yes can help Samba return + out of quota messages on systems that are restricting the disk quota + of users. + + Default: strict allocate = no + + diff --git a/docs/docbook/smbdotconf/tuning/strictsync.xml b/docs/docbook/smbdotconf/tuning/strictsync.xml new file mode 100644 index 0000000000..b228f7cfcb --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/strictsync.xml @@ -0,0 +1,23 @@ + + strict sync (S) + Many Windows applications (including the Windows + 98 explorer shell) seem to confuse flushing buffer contents to + disk with doing a sync to disk. Under UNIX, a sync call forces + the process to be suspended until the kernel has ensured that + all outstanding data in kernel disk buffers has been safely stored + onto stable storage. This is very slow and should only be done + rarely. Setting this parameter to no (the + default) means that smbd + 8 ignores the Windows applications requests for + a sync call. There is only a possibility of losing data if the + operating system itself that Samba is running on crashes, so there is + little danger in this default setting. In addition, this fixes many + performance problems that people have reported with the new Windows98 + explorer shell file copies. + + See also the sync + always> parameter. + + Default: strict sync = no + + diff --git a/docs/docbook/smbdotconf/tuning/syncalways.xml b/docs/docbook/smbdotconf/tuning/syncalways.xml new file mode 100644 index 0000000000..c5c32343a7 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/syncalways.xml @@ -0,0 +1,19 @@ + + sync always (S) + This is a boolean parameter that controls + whether writes will always be written to stable storage before + the write call returns. If this is no then the server will be + guided by the client's request in each write call (clients can + set a bit indicating that a particular write should be synchronous). + If this is yes then every write will be followed by a fsync() + call to ensure the data is written to disk. Note that + the strict sync parameter must be set to + yes in order for this parameter to have + any affect. + + See also the strict + sync parameter. + + Default: sync always = no + + diff --git a/docs/docbook/smbdotconf/tuning/usemmap.xml b/docs/docbook/smbdotconf/tuning/usemmap.xml new file mode 100644 index 0000000000..46fa4600de --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/usemmap.xml @@ -0,0 +1,14 @@ + + use mmap (G) + This global parameter determines if the tdb internals of Samba can + depend on mmap working correctly on the running system. Samba requires a coherent + mmap/read-write system memory cache. Currently only HPUX does not have such a + coherent cache, and so this parameter is set to no by + default on HPUX. On all other systems this parameter should be left alone. This + parameter is provided to help the Samba developers track down problems with + the tdb internal code. + + + Default: use mmap = yes + + diff --git a/docs/docbook/smbdotconf/tuning/usesendfile.xml b/docs/docbook/smbdotconf/tuning/usesendfile.xml new file mode 100644 index 0000000000..5f2dcb72a9 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/usesendfile.xml @@ -0,0 +1,14 @@ + + use sendfile (S) + If this parameter is yes, and Samba + was built with the --with-sendfile-support option, and the underlying operating + system supports sendfile system call, then some SMB read calls (mainly ReadAndX + and ReadRaw) will use the more efficient sendfile system call for files that + are exclusively oplocked. This may make more efficient use of the system CPU's + and cause Samba to be faster. This is off by default as it's effects are unknown + as yet. + + + Default: use sendfile = no + + diff --git a/docs/docbook/smbdotconf/tuning/writecachesize.xml b/docs/docbook/smbdotconf/tuning/writecachesize.xml new file mode 100644 index 0000000000..b54a0e4fd6 --- /dev/null +++ b/docs/docbook/smbdotconf/tuning/writecachesize.xml @@ -0,0 +1,27 @@ + + write cache size (S) + If this integer parameter is set to non-zero value, + Samba will create an in-memory cache for each oplocked file + (it does not do this for + non-oplocked files). All writes that the client does not request + to be flushed directly to disk will be stored in this cache if possible. + The cache is flushed onto disk when a write comes in whose offset + would not fit into the cache or when the file is closed by the client. + Reads for the file are also served from this cache if the data is stored + within it. + + This cache allows Samba to batch client writes into a more + efficient write size for RAID disks (i.e. writes may be tuned to + be the RAID stripe size) and can improve performance on systems + where the disk subsystem is a bottleneck but there is free + memory for userspace programs. + + The integer parameter specifies the size of this cache + (per oplocked file) in bytes. + + Default: write cache size = 0 + Example: write cache size = 262144 + + for a 256k cache size per file. + + diff --git a/docs/docbook/smbdotconf/vfs/hostmsdfs.xml b/docs/docbook/smbdotconf/vfs/hostmsdfs.xml new file mode 100644 index 0000000000..0496fd7f47 --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/hostmsdfs.xml @@ -0,0 +1,17 @@ + + host msdfs (G) + This boolean parameter is only available + if Samba has been configured and compiled with the + --with-msdfs option. If set to yes, + Samba will act as a Dfs server, and allow Dfs-aware clients + to browse Dfs trees hosted on the server. + + See also the + msdfs root share level parameter. For + more information on setting up a Dfs tree on Samba, + refer to msdfs_setup.html. + + + Default: host msdfs = no + + diff --git a/docs/docbook/smbdotconf/vfs/msdfsproxy.xml b/docs/docbook/smbdotconf/vfs/msdfsproxy.xml new file mode 100644 index 0000000000..41b36cb91b --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/msdfsproxy.xml @@ -0,0 +1,15 @@ + + msdfs proxy (S) + This parameter indicates that the share is a + stand-in for another CIFS share whose location is specified by + the value of the parameter. When clients attempt to connect to + this share, they are redirected to the proxied share using + the SMB-Dfs protocol. + Only Dfs roots can act as proxy shares. Take a look at the + msdfs root + and + host msdfs + options to find out how to set up a Dfs root share. + Example: msdfs proxy = \\\\otherserver\\someshare + + diff --git a/docs/docbook/smbdotconf/vfs/msdfsroot.xml b/docs/docbook/smbdotconf/vfs/msdfsroot.xml new file mode 100644 index 0000000000..dc50ba5e57 --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/msdfsroot.xml @@ -0,0 +1,19 @@ + + msdfs root (S) + This boolean parameter is only available if + Samba is configured and compiled with the + --with-msdfs option. If set to yes, + Samba treats the share as a Dfs root and allows clients to browse + the distributed file system tree rooted at the share directory. + Dfs links are specified in the share directory by symbolic + links of the form msdfs:serverA\\shareA,serverB\\shareB + and so on. For more information on setting up a Dfs tree + on Samba, refer to "Hosting a Microsoft + Distributed File System tree on Samba" document. + + See also host msdfs + + + Default: msdfs root = no + + diff --git a/docs/docbook/smbdotconf/vfs/vfsobject.xml b/docs/docbook/smbdotconf/vfs/vfsobject.xml new file mode 100644 index 0000000000..d334552dae --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/vfsobject.xml @@ -0,0 +1,10 @@ + + vfs object (S) + This parameter specifies a shared object files that + are used for Samba VFS I/O operations. By default, normal + disk I/O operations are used but these can be overloaded + with one or more VFS objects. + + Default : no value + + diff --git a/docs/docbook/smbdotconf/vfs/vfsoptions.xml b/docs/docbook/smbdotconf/vfs/vfsoptions.xml new file mode 100644 index 0000000000..28f14a09bf --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/vfsoptions.xml @@ -0,0 +1,10 @@ + + vfs options (S) + This parameter allows parameters to be passed + to the vfs layer at initialization time. + See also + vfs object. + + Default : no value + + diff --git a/docs/docbook/smbdotconf/vfs/vfspath.xml b/docs/docbook/smbdotconf/vfs/vfspath.xml new file mode 100644 index 0000000000..78c27302a8 --- /dev/null +++ b/docs/docbook/smbdotconf/vfs/vfspath.xml @@ -0,0 +1,12 @@ + + vfs path (S) + This parameter specifies the directory + to look in for vfs modules. The name of every vfs object + will be prepended by this directory + + + Default: vfs path = + Example: vfs path = /usr/lib/samba/vfs + + + diff --git a/docs/docbook/smbdotconf/winbind/templatehomedir.xml b/docs/docbook/smbdotconf/winbind/templatehomedir.xml new file mode 100644 index 0000000000..a931e9b5a3 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/templatehomedir.xml @@ -0,0 +1,13 @@ + + template homedir (G) + When filling out the user information for a Windows NT + user, the winbindd(8) daemon + uses this parameter to fill in the home directory for that user. + If the string %D is present it is substituted + with the user's Windows NT domain name. If the string %U + is present it is substituted with the user's Windows + NT user name. + + Default: template homedir = /home/%D/%U + + diff --git a/docs/docbook/smbdotconf/winbind/templateshell.xml b/docs/docbook/smbdotconf/winbind/templateshell.xml new file mode 100644 index 0000000000..e0b9f1a2ca --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/templateshell.xml @@ -0,0 +1,10 @@ + + template shell (G) + When filling out the user information for a Windows NT + user, the winbindd + 8 daemon + uses this parameter to fill in the login shell for that user. + + Default: template shell = /bin/false + + diff --git a/docs/docbook/smbdotconf/winbind/winbindcachetime.xml b/docs/docbook/smbdotconf/winbind/winbindcachetime.xml new file mode 100644 index 0000000000..adbb8b12f6 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindcachetime.xml @@ -0,0 +1,11 @@ + + winbind cache time (G) + This parameter specifies the number of + seconds the winbindd + 8 daemon will cache + user and group information before querying a Windows NT server + again. + + Default: winbind cache type = 15 + + diff --git a/docs/docbook/smbdotconf/winbind/winbindenumgroups.xml b/docs/docbook/smbdotconf/winbind/winbindenumgroups.xml new file mode 100644 index 0000000000..096c280fc2 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindenumgroups.xml @@ -0,0 +1,18 @@ + + winbind enum groups (G) + On large installations using winbindd + 8 it may be necessary to suppress + the enumeration of groups through the setgrent(), + getgrent() and + endgrent() group of system calls. If + the winbind enum groups parameter is + no, calls to the getgrent() system + call will not return any data. + + Warning: Turning off group + enumeration may cause some programs to behave oddly. + + + Default: winbind enum groups = yes + + diff --git a/docs/docbook/smbdotconf/winbind/winbindenumusers.xml b/docs/docbook/smbdotconf/winbind/winbindenumusers.xml new file mode 100644 index 0000000000..7935755f0c --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindenumusers.xml @@ -0,0 +1,20 @@ + + winbind enum users (G) + On large installations using winbindd + 8 it may be + necessary to suppress the enumeration of users through the setpwent(), + getpwent() and + endpwent() group of system calls. If + the winbind enum users parameter is + no, calls to the getpwent system call + will not return any data. + + Warning: Turning off user + enumeration may cause some programs to behave oddly. For + example, the finger program relies on having access to the + full user list when searching for matching + usernames. + + Default: winbind enum users = yes + + diff --git a/docs/docbook/smbdotconf/winbind/winbindgid.xml b/docs/docbook/smbdotconf/winbind/winbindgid.xml new file mode 100644 index 0000000000..a8a9683b01 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindgid.xml @@ -0,0 +1,14 @@ + + winbind gid (G) + The winbind gid parameter specifies the range of group + ids that are allocated by the winbindd + 8 daemon. This range of group ids should have no + existing local or NIS groups within it as strange conflicts can + occur otherwise. + + Default: winbind gid = <empty string> + + + Example: winbind gid = 10000-20000 + + diff --git a/docs/docbook/smbdotconf/winbind/winbindseparator.xml b/docs/docbook/smbdotconf/winbind/winbindseparator.xml new file mode 100644 index 0000000000..416adcb531 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindseparator.xml @@ -0,0 +1,17 @@ + + winbind separator (G) + This parameter allows an admin to define the character + used when listing a username of the form of DOMAIN + \user. This parameter + is only applicable when using the pam_winbind.so + and nss_winbind.so modules for UNIX services. + + + Please note that setting this parameter to + causes problems + with group membership at least on glibc systems, as the character + + is used as a special character for NIS in /etc/group. + + Default: winbind separator = '\' + Example: winbind separator = + + + diff --git a/docs/docbook/smbdotconf/winbind/winbinduid.xml b/docs/docbook/smbdotconf/winbind/winbinduid.xml new file mode 100644 index 0000000000..ecd7848f61 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbinduid.xml @@ -0,0 +1,14 @@ + + winbind uid (G) + The winbind gid parameter specifies the range of group + ids that are allocated by the winbindd + 8 daemon. This range of ids should have no + existing local or NIS users within it as strange conflicts can + occur otherwise. + + Default: winbind uid = <empty string> + + + Example: winbind uid = 10000-20000 + + diff --git a/docs/docbook/smbdotconf/winbind/winbindusedefaultdomain.xml b/docs/docbook/smbdotconf/winbind/winbindusedefaultdomain.xml new file mode 100644 index 0000000000..a6b7bcd7e5 --- /dev/null +++ b/docs/docbook/smbdotconf/winbind/winbindusedefaultdomain.xml @@ -0,0 +1,14 @@ + + winbind use default domain (G) + This parameter specifies whether the winbindd + 8 daemon should operate on users + without domain component in their username. + Users without a domain component are treated as is part of the winbindd server's + own domain. While this does not benifit Windows users, it makes SSH, FTP and e-mail + function in a way much closer to the way they would in a native unix system. + + Default: winbind use default domain = <no> + + Example: winbind use default domain = yes + + diff --git a/docs/docbook/smbdotconf/wins/dnsproxy.xml b/docs/docbook/smbdotconf/wins/dnsproxy.xml new file mode 100644 index 0000000000..fd53ae7ded --- /dev/null +++ b/docs/docbook/smbdotconf/wins/dnsproxy.xml @@ -0,0 +1,21 @@ + + dns proxy (G) + Specifies that nmbd + 8 when acting as a WINS server and + finding that a NetBIOS name has not been registered, should treat the + NetBIOS name word-for-word as a DNS name and do a lookup with the DNS server + for that name on behalf of the name-querying client. + + Note that the maximum length for a NetBIOS name is 15 + characters, so the DNS name (or DNS alias) can likewise only be + 15 characters, maximum. + + nmbd spawns a second copy of itself to do the + DNS name lookup requests, as doing a name lookup is a blocking + action. + + See also the parameter + wins support. + + Default: dns proxy = yes + diff --git a/docs/docbook/smbdotconf/wins/winshook.xml b/docs/docbook/smbdotconf/wins/winshook.xml new file mode 100644 index 0000000000..e0c4a87c5b --- /dev/null +++ b/docs/docbook/smbdotconf/wins/winshook.xml @@ -0,0 +1,43 @@ + + wins hook (G) + When Samba is running as a WINS server this + allows you to call an external program for all changes to the + WINS database. The primary use for this option is to allow the + dynamic update of external name resolution databases such as + dynamic DNS. + + The wins hook parameter specifies the name of a script + or executable that will be called as follows: + + wins_hook operation name nametype ttl IP_list + + + + The first argument is the operation and is one + of "add", "delete", or "refresh". In most cases the operation can + be ignored as the rest of the parameters provide sufficient + information. Note that "refresh" may sometimes be called when the + name has not previously been added, in that case it should be treated + as an add. + + The second argument is the NetBIOS name. If the + name is not a legal name then the wins hook is not called. + Legal names contain only letters, digits, hyphens, underscores + and periods. + + The third argument is the NetBIOS name + type as a 2 digit hexadecimal number. + + The fourth argument is the TTL (time to live) + for the name in seconds. + + The fifth and subsequent arguments are the IP + addresses currently registered for that name. If this list is + empty then the name should be deleted. + + + An example script that calls the BIND dynamic DNS update + program nsupdate is provided in the examples + directory of the Samba source code. + + diff --git a/docs/docbook/smbdotconf/wins/winspartners.xml b/docs/docbook/smbdotconf/wins/winspartners.xml new file mode 100644 index 0000000000..840435ae4e --- /dev/null +++ b/docs/docbook/smbdotconf/wins/winspartners.xml @@ -0,0 +1,14 @@ + + wins partners (G) + A space separated list of partners' IP addresses for + WINS replication. WINS partners are always defined as push/pull + partners as defining only one way WINS replication is unreliable. + WINS replication is currently experimental and unreliable between + samba servers. + + + Default: wins partners = + + Example: wins partners = 192.168.0.1 172.16.1.2 + + diff --git a/docs/docbook/smbdotconf/wins/winsproxy.xml b/docs/docbook/smbdotconf/wins/winsproxy.xml new file mode 100644 index 0000000000..31978d3b24 --- /dev/null +++ b/docs/docbook/smbdotconf/wins/winsproxy.xml @@ -0,0 +1,9 @@ + + wins proxy (G) + This is a boolean that controls if nmbd(8) will respond to broadcast name + queries on behalf of other hosts. You may need to set this + to yes for some older clients. + + Default: wins proxy = no + + diff --git a/docs/docbook/smbdotconf/wins/winsserver.xml b/docs/docbook/smbdotconf/wins/winsserver.xml new file mode 100644 index 0000000000..ba49f687f6 --- /dev/null +++ b/docs/docbook/smbdotconf/wins/winsserver.xml @@ -0,0 +1,21 @@ + + wins server (G) + This specifies the IP address (or DNS name: IP + address for preference) of the WINS server that nmbd + 8 should register with. If you have a WINS server on + your network then you should set this to the WINS server's IP. + + You should point this at your WINS server if you have a + multi-subnetted network. + + NOTE. You need to set up Samba to point + to a WINS server if you have multiple subnets and wish cross-subnet + browsing to work correctly. + + See the documentation file BROWSING + in the docs/ directory of your Samba source distribution. + + Default: not enabled + Example: wins server = 192.9.200.1 + + diff --git a/docs/docbook/smbdotconf/wins/winssupport.xml b/docs/docbook/smbdotconf/wins/winssupport.xml new file mode 100644 index 0000000000..5ad886a9b1 --- /dev/null +++ b/docs/docbook/smbdotconf/wins/winssupport.xml @@ -0,0 +1,12 @@ + + wins support (G) + This boolean controls if the nmbd + 8 process in Samba will act as a WINS server. You should + not set this to yes unless you have a multi-subnetted network and + you wish a particular nmbd to be your WINS server. + Note that you should NEVER set this to yes + on more than one machine in your network. + + Default: wins support = no + + -- cgit From 2b984c620814b1258c8b4e006dde370b19b4461d Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Thu, 27 Mar 2003 18:28:55 +0000 Subject: 1. Fix generate-file-list.sh to produce a list sorted by parameter name, not parameter section. 2. Convert base parameters to new meta-information scheme (This used to be commit 6026e47cfe493625c6ed017ecae3cc785a6d0347) --- .../docbook/smbdotconf/base/bindinterfacesonly.xml | 123 +++++++++++---------- docs/docbook/smbdotconf/base/comment.xml | 28 +++-- docs/docbook/smbdotconf/base/directory.xml | 14 ++- docs/docbook/smbdotconf/base/displaycharset.xml | 23 ++-- docs/docbook/smbdotconf/base/doscharset.xml | 28 ++--- docs/docbook/smbdotconf/base/interfaces.xml | 76 ++++++------- docs/docbook/smbdotconf/base/netbiosaliases.xml | 33 +++--- docs/docbook/smbdotconf/base/netbiosname.xml | 32 +++--- docs/docbook/smbdotconf/base/netbiosscope.xml | 17 +-- docs/docbook/smbdotconf/base/path.xml | 50 +++++---- docs/docbook/smbdotconf/base/realm.xml | 25 +++-- docs/docbook/smbdotconf/base/serverstring.xml | 36 +++--- docs/docbook/smbdotconf/base/unixcharset.xml | 24 ++-- docs/docbook/smbdotconf/base/workgroup.xml | 25 +++-- docs/docbook/smbdotconf/generate-file-list.sh | 2 +- docs/docbook/smbdotconf/smbconf.dtd | 3 + 16 files changed, 295 insertions(+), 244 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/smbdotconf/base/bindinterfacesonly.xml b/docs/docbook/smbdotconf/base/bindinterfacesonly.xml index 78e1b02bf5..3ad9aa4614 100644 --- a/docs/docbook/smbdotconf/base/bindinterfacesonly.xml +++ b/docs/docbook/smbdotconf/base/bindinterfacesonly.xml @@ -1,66 +1,71 @@ - - bind interfaces only (G) - This global parameter allows the Samba admin - to limit what interfaces on a machine will serve SMB requests. It - affects file service smbd - 8 and name service nmbd - 8 in a slightly different ways. + + + This global parameter allows the Samba admin + to limit what interfaces on a machine will serve SMB requests. It + affects file service smbd + 8 and name service nmbd + 8 in a slightly different ways. - For name service it causes nmbd to bind - to ports 137 and 138 on the interfaces listed in the interfaces parameter. nmbd - also binds to the "all addresses" interface (0.0.0.0) - on ports 137 and 138 for the purposes of reading broadcast messages. - If this option is not set then nmbd will service - name requests on all of these sockets. If bind interfaces - only is set then nmbd will check the - source address of any packets coming in on the broadcast sockets - and discard any that don't match the broadcast addresses of the - interfaces in the interfaces parameter list. - As unicast packets are received on the other sockets it allows - nmbd to refuse to serve names to machines that - send packets that arrive through any interfaces not listed in the - interfaces list. IP Source address spoofing - does defeat this simple check, however, so it must not be used - seriously as a security feature for nmbd. + For name service it causes nmbd to bind + to ports 137 and 138 on the interfaces listed in + the interfaces parameter. nmbd also + binds to the "all addresses" interface (0.0.0.0) + on ports 137 and 138 for the purposes of reading broadcast messages. + If this option is not set then nmbd will service + name requests on all of these sockets. If bind interfaces + only is set then nmbd will check the + source address of any packets coming in on the broadcast sockets + and discard any that don't match the broadcast addresses of the + interfaces in the interfaces parameter list. + As unicast packets are received on the other sockets it allows + nmbd to refuse to serve names to machines that + send packets that arrive through any interfaces not listed in the + interfaces list. IP Source address spoofing + does defeat this simple check, however, so it must not be used + seriously as a security feature for nmbd. - For file service it causes smbd - 8 to bind only to the interface list - given in the - interfaces parameter. This restricts the networks that - smbd will serve to packets coming in those - interfaces. Note that you should not use this parameter for machines - that are serving PPP or other intermittent or non-broadcast network - interfaces as it will not cope with non-permanent interfaces. + For file service it causes smbd + 8 to bind only to the interface list + given in the interfaces parameter. This + restricts the networks that smbd will serve + to packets coming in those interfaces. Note that you should not use this parameter + for machines that are serving PPP or other intermittent or non-broadcast network + interfaces as it will not cope with non-permanent interfaces. - If bind interfaces only is set then - unless the network address 127.0.0.1 is added - to the interfaces parameter list smbpasswd - 8 and swat - 8 may not work as expected due to the reasons covered below. + If bind interfaces only is set then + unless the network address 127.0.0.1 is added + to the interfaces parameter + list smbpasswd + 8 and swat + 8 may not work as expected due + to the reasons covered below. - To change a users SMB password, the smbpasswd - by default connects to the localhost - 127.0.0.1 - address as an SMB client to issue the password change request. If - bind interfaces only is set then unless the - network address 127.0.0.1 is added to the - interfaces parameter list then - smbpasswd will fail to connect in it's default mode. - smbpasswd can be forced to use the primary IP interface - of the local host by using its smbpasswd - 8 -r remote machine - parameter, with remote machine set - to the IP name of the primary interface of the local host. + To change a users SMB password, the smbpasswd + by default connects to the localhost - 127.0.0.1 + address as an SMB client to issue the password change request. If + bind interfaces only is set then unless the + network address 127.0.0.1 is added to the + interfaces parameter list then + smbpasswd will fail to connect in it's default mode. + smbpasswd can be forced to use the primary IP interface + of the local host by using its smbpasswd + 8 -r remote machine + parameter, with remote machine set + to the IP name of the primary interface of the local host. - The swat status page tries to connect with - smbd and nmbd at the address - 127.0.0.1 to determine if they are running. - Not adding 127.0.0.1 will cause - smbd and nmbd to always show - "not running" even if they really are. This can prevent - swat from starting/stopping/restarting smbd - and nmbd. + The swat status page tries to connect with + smbd and nmbd at the address + 127.0.0.1 to determine if they are running. + Not adding 127.0.0.1 will cause + smbd and nmbd to always show + "not running" even if they really are. This can prevent + swat from starting/stopping/restarting smbd + and nmbd. - Default: bind interfaces only = no + Default: bind interfaces only = no - - + + diff --git a/docs/docbook/smbdotconf/base/comment.xml b/docs/docbook/smbdotconf/base/comment.xml index 693268a0b0..f08d06ef25 100644 --- a/docs/docbook/smbdotconf/base/comment.xml +++ b/docs/docbook/smbdotconf/base/comment.xml @@ -1,14 +1,18 @@ - - comment (S) - This is a text field that is seen next to a share - when a client does a queries the server, either via the network - neighborhood or via net view to list what shares - are available. + + + This is a text field that is seen next to a share + when a client does a queries the server, either via the network + neighborhood or via net view to list what shares + are available. - If you want to set the string that is displayed next to the - machine name then see the - server string parameter. + If you want to set the string that is displayed next to the + machine name then see the + server string parameter. - Default: No comment string - Example: comment = Fred's Files - + Default: No comment string + Example: comment = Fred's Files + + diff --git a/docs/docbook/smbdotconf/base/directory.xml b/docs/docbook/smbdotconf/base/directory.xml index 1ec4ab7e1a..f912c39c8c 100644 --- a/docs/docbook/smbdotconf/base/directory.xml +++ b/docs/docbook/smbdotconf/base/directory.xml @@ -1,5 +1,9 @@ - - directory (S) - Synonym for path - . - + + + + Synonym for path. + + diff --git a/docs/docbook/smbdotconf/base/displaycharset.xml b/docs/docbook/smbdotconf/base/displaycharset.xml index add519e783..e02842ab48 100644 --- a/docs/docbook/smbdotconf/base/displaycharset.xml +++ b/docs/docbook/smbdotconf/base/displaycharset.xml @@ -1,13 +1,16 @@ - - display charset (G) - Specifies the charset that samba will use - to print messages to stdout and stderr and SWAT will use. - Should generally be the same as the unix charset. - + + + Specifies the charset that samba will use + to print messages to stdout and stderr and SWAT will use. + Should generally be the same as the unix charset. + - Default: display charset = ASCII + Default: display charset = ASCII - Example: display charset = UTF8 + Example: display charset = UTF8 - - + + diff --git a/docs/docbook/smbdotconf/base/doscharset.xml b/docs/docbook/smbdotconf/base/doscharset.xml index db767e720c..5fc718dcaa 100644 --- a/docs/docbook/smbdotconf/base/doscharset.xml +++ b/docs/docbook/smbdotconf/base/doscharset.xml @@ -1,14 +1,16 @@ - - dos charset (G) - DOS SMB clients assume the server has - the same charset as they do. This option specifies which - charset Samba should talk to DOS clients. - + + + DOS SMB clients assume the server has + the same charset as they do. This option specifies which + charset Samba should talk to DOS clients. + - The default depends on which charsets you have installed. - Samba tries to use charset 850 but falls back to ASCII in - case it is not available. Run testparm - 1 to check the default on your system. - - - + The default depends on which charsets you have installed. + Samba tries to use charset 850 but falls back to ASCII in + case it is not available. Run testparm + 1 to check the default on your system. + + diff --git a/docs/docbook/smbdotconf/base/interfaces.xml b/docs/docbook/smbdotconf/base/interfaces.xml index 1125ad0559..3fa346e206 100644 --- a/docs/docbook/smbdotconf/base/interfaces.xml +++ b/docs/docbook/smbdotconf/base/interfaces.xml @@ -1,49 +1,51 @@ - - interfaces (G) - This option allows you to override the default - network interfaces list that Samba will use for browsing, name - registration and other NBT traffic. By default Samba will query - the kernel for the list of all active interfaces and use any - interfaces except 127.0.0.1 that are broadcast capable. + + + This option allows you to override the default + network interfaces list that Samba will use for browsing, name + registration and other NBT traffic. By default Samba will query + the kernel for the list of all active interfaces and use any + interfaces except 127.0.0.1 that are broadcast capable. - The option takes a list of interface strings. Each string - can be in any of the following forms: + The option takes a list of interface strings. Each string + can be in any of the following forms: - - a network interface name (such as eth0). - This may include shell-like wildcards so eth* will match - any interface starting with the substring "eth" + + a network interface name (such as eth0). + This may include shell-like wildcards so eth* will match + any interface starting with the substring "eth" - an IP address. In this case the netmask is - determined from the list of interfaces obtained from the - kernel + an IP address. In this case the netmask is + determined from the list of interfaces obtained from the + kernel - an IP/mask pair. + an IP/mask pair. - a broadcast/mask pair. - + a broadcast/mask pair. + - The "mask" parameters can either be a bit length (such - as 24 for a C class network) or a full netmask in dotted - decimal form. + The "mask" parameters can either be a bit length (such + as 24 for a C class network) or a full netmask in dotted + decimal form. - The "IP" parameters above can either be a full dotted - decimal IP address or a hostname which will be looked up via - the OS's normal hostname resolution mechanisms. + The "IP" parameters above can either be a full dotted + decimal IP address or a hostname which will be looked up via + the OS's normal hostname resolution mechanisms. - For example, the following line: + For example, the following line: - interfaces = eth0 192.168.2.10/24 192.168.3.10/255.255.255.0 - + interfaces = eth0 192.168.2.10/24 192.168.3.10/255.255.255.0 - would configure three network interfaces corresponding - to the eth0 device and IP addresses 192.168.2.10 and 192.168.3.10. - The netmasks of the latter two interfaces would be set to 255.255.255.0. + would configure three network interfaces corresponding + to the eth0 device and IP addresses 192.168.2.10 and 192.168.3.10. + The netmasks of the latter two interfaces would be set to 255.255.255.0. - See also bind - interfaces only. + See also bind + interfaces only. - Default: all active interfaces except 127.0.0.1 - that are broadcast capable - - + Default: all active interfaces except 127.0.0.1 + that are broadcast capable + + diff --git a/docs/docbook/smbdotconf/base/netbiosaliases.xml b/docs/docbook/smbdotconf/base/netbiosaliases.xml index b0a7688a83..a62fb8f7d6 100644 --- a/docs/docbook/smbdotconf/base/netbiosaliases.xml +++ b/docs/docbook/smbdotconf/base/netbiosaliases.xml @@ -1,17 +1,20 @@ - - netbios aliases (G) - This is a list of NetBIOS names that nmbd(8) will advertise as additional - names by which the Samba server is known. This allows one machine - to appear in browse lists under multiple names. If a machine is - acting as a browse server or logon server none - of these names will be advertised as either browse server or logon - servers, only the primary name of the machine will be advertised - with these capabilities. + + + This is a list of NetBIOS names that nmbd(8) will + advertise as additional names by which the Samba server is known. This allows one machine + to appear in browse lists under multiple names. If a machine is acting as a browse server + or logon server none of these names will be advertised as either browse server or logon + servers, only the primary name of the machine will be advertised with these capabilities. + - See also netbios - name. + See also netbios + name. - Default: empty string (no additional names) - Example: netbios aliases = TEST TEST1 TEST2 - - + Default: empty string (no additional names) + + Example: netbios aliases = TEST TEST1 TEST2 + + diff --git a/docs/docbook/smbdotconf/base/netbiosname.xml b/docs/docbook/smbdotconf/base/netbiosname.xml index 2daf26e2b3..287a8f9f9f 100644 --- a/docs/docbook/smbdotconf/base/netbiosname.xml +++ b/docs/docbook/smbdotconf/base/netbiosname.xml @@ -1,16 +1,20 @@ - - netbios name (G) - This sets the NetBIOS name by which a Samba - server is known. By default it is the same as the first component - of the host's DNS name. If a machine is a browse server or - logon server this name (or the first component - of the hosts DNS name) will be the name that these services are - advertised under. + + + This sets the NetBIOS name by which a Samba + server is known. By default it is the same as the first component + of the host's DNS name. If a machine is a browse server or + logon server this name (or the first component + of the hosts DNS name) will be the name that these services are + advertised under. - See also netbios - aliases. + See also netbios + aliases. - Default: machine DNS name - Example: netbios name = MYNAME - - + Default: machine DNS name + + Example: netbios name = MYNAME + + diff --git a/docs/docbook/smbdotconf/base/netbiosscope.xml b/docs/docbook/smbdotconf/base/netbiosscope.xml index fd0e4ad40c..8c5866bc32 100644 --- a/docs/docbook/smbdotconf/base/netbiosscope.xml +++ b/docs/docbook/smbdotconf/base/netbiosscope.xml @@ -1,7 +1,10 @@ - - netbios scope (G) - This sets the NetBIOS scope that Samba will - operate under. This should not be set unless every machine - on your LAN also sets this value. - - + + + This sets the NetBIOS scope that Samba will + operate under. This should not be set unless every machine + on your LAN also sets this value. + + diff --git a/docs/docbook/smbdotconf/base/path.xml b/docs/docbook/smbdotconf/base/path.xml index 7d65e10b2b..9f0a7cd976 100644 --- a/docs/docbook/smbdotconf/base/path.xml +++ b/docs/docbook/smbdotconf/base/path.xml @@ -1,27 +1,31 @@ - - path (S) - This parameter specifies a directory to which - the user of the service is to be given access. In the case of - printable services, this is where print data will spool prior to - being submitted to the host for printing. + + + This parameter specifies a directory to which + the user of the service is to be given access. In the case of + printable services, this is where print data will spool prior to + being submitted to the host for printing. - For a printable service offering guest access, the service - should be readonly and the path should be world-writeable and - have the sticky bit set. This is not mandatory of course, but - you probably won't get the results you expect if you do - otherwise. + For a printable service offering guest access, the service + should be readonly and the path should be world-writeable and + have the sticky bit set. This is not mandatory of course, but + you probably won't get the results you expect if you do + otherwise. - Any occurrences of %u in the path - will be replaced with the UNIX username that the client is using - on this connection. Any occurrences of %m - will be replaced by the NetBIOS name of the machine they are - connecting from. These replacements are very useful for setting - up pseudo home directories for users. + Any occurrences of %u in the path + will be replaced with the UNIX username that the client is using + on this connection. Any occurrences of %m + will be replaced by the NetBIOS name of the machine they are + connecting from. These replacements are very useful for setting + up pseudo home directories for users. - Note that this path will be based on - root dir if one was specified. + Note that this path will be based on + root dir if one was specified. - Default: none - Example: path = /home/fred - - + Default: none + + Example: path = /home/fred + + diff --git a/docs/docbook/smbdotconf/base/realm.xml b/docs/docbook/smbdotconf/base/realm.xml index 50c7d26eea..c0b1d1aad6 100644 --- a/docs/docbook/smbdotconf/base/realm.xml +++ b/docs/docbook/smbdotconf/base/realm.xml @@ -1,12 +1,15 @@ - - realm (G) - - This option specifies the kerberos realm to use. The realm is - used as the ADS equivalent of the NT4domain. It - is usually set to the DNS name of the kerberos server. - + + + This option specifies the kerberos realm to use. The realm is + used as the ADS equivalent of the NT4 domain. It + is usually set to the DNS name of the kerberos server. + - Default: realm = - Example: realm = mysambabox.mycompany.com - - + Default: realm = + + Example: realm = mysambabox.mycompany.com + + diff --git a/docs/docbook/smbdotconf/base/serverstring.xml b/docs/docbook/smbdotconf/base/serverstring.xml index a47ac4cf42..5935dd80dd 100644 --- a/docs/docbook/smbdotconf/base/serverstring.xml +++ b/docs/docbook/smbdotconf/base/serverstring.xml @@ -1,22 +1,24 @@ - - server string (G) - This controls what string will show up in the - printer comment box in print manager and next to the IPC connection - in net view. It can be any string that you wish - to show to your users. + + + This controls what string will show up in the printer comment box in print + manager and next to the IPC connection in net view. It + can be any string that you wish to show to your users. - It also sets what will appear in browse lists next - to the machine name. + It also sets what will appear in browse lists next + to the machine name. - A %v will be replaced with the Samba - version number. + A %v will be replaced with the Samba + version number. - A %h will be replaced with the - hostname. + A %h will be replaced with the + hostname. - Default: server string = Samba %v + Default: server string = Samba %v - Example: server string = University of GNUs Samba - Server - - + Example: server string = University of GNUs Samba + Server + + diff --git a/docs/docbook/smbdotconf/base/unixcharset.xml b/docs/docbook/smbdotconf/base/unixcharset.xml index 0ea84e38c8..f003c097aa 100644 --- a/docs/docbook/smbdotconf/base/unixcharset.xml +++ b/docs/docbook/smbdotconf/base/unixcharset.xml @@ -1,11 +1,15 @@ - - unix charset (G) - Specifies the charset the unix machine - Samba runs on uses. Samba needs to know this in order to be able to - convert text to the charsets other SMB clients use. - + + + Specifies the charset the unix machine + Samba runs on uses. Samba needs to know this in order to be able to + convert text to the charsets other SMB clients use. + - Default: unix charset = UTF8 - Example: unix charset = ASCII - - + Default: unix charset = UTF8 + + Example: unix charset = ASCII + + diff --git a/docs/docbook/smbdotconf/base/workgroup.xml b/docs/docbook/smbdotconf/base/workgroup.xml index 71ea89d202..65300bca58 100644 --- a/docs/docbook/smbdotconf/base/workgroup.xml +++ b/docs/docbook/smbdotconf/base/workgroup.xml @@ -1,11 +1,16 @@ - - workgroup (G) - This controls what workgroup your server will - appear to be in when queried by clients. Note that this parameter - also controls the Domain name used with the security = domain - setting. + + + This controls what workgroup your server will + appear to be in when queried by clients. Note that this parameter + also controls the Domain name used with + the security = domain + setting. - Default: set at compile time to WORKGROUP - Example: workgroup = MYGROUP - - + Default: set at compile time to WORKGROUP + + Example: workgroup = MYGROUP + + diff --git a/docs/docbook/smbdotconf/generate-file-list.sh b/docs/docbook/smbdotconf/generate-file-list.sh index f61ac4f49c..3495f50c43 100755 --- a/docs/docbook/smbdotconf/generate-file-list.sh +++ b/docs/docbook/smbdotconf/generate-file-list.sh @@ -1,6 +1,6 @@ #!/bin/sh echo "" -find . -type f -name '*.xml' -mindepth 2 | sort | +find . -type f -name '*.xml' -mindepth 2 | sort -t/ -k3 | while read ; do echo "" done diff --git a/docs/docbook/smbdotconf/smbconf.dtd b/docs/docbook/smbdotconf/smbconf.dtd index 00340a7db9..591c9b2738 100644 --- a/docs/docbook/smbdotconf/smbconf.dtd +++ b/docs/docbook/smbdotconf/smbconf.dtd @@ -4,4 +4,7 @@ + + + -- cgit From e14903cc92ffe30bfdbba3b5718a281cacb1400b Mon Sep 17 00:00:00 2001 From: Alexander Bokovoy Date: Thu, 27 Mar 2003 18:56:42 +0000 Subject: Reflect current conversion status (This used to be commit 8f1c78df1088beeb11de54b0369b4e5f036004d4) --- docs/docbook/smbdotconf/README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/docbook') diff --git a/docs/docbook/smbdotconf/README b/docs/docbook/smbdotconf/README index f50a944e7b..e69d30af5f 100644 --- a/docs/docbook/smbdotconf/README +++ b/docs/docbook/smbdotconf/README @@ -149,7 +149,7 @@ process-all.sh Current state of converted parameters ------------------------------------- -Only 'ads server' parameter converted so far to serve as example of +Only 'base' parameters converted so far to serve as example of formatting. All undocumented parameters are listed in doc-status file in of Samba's -- cgit From c321404feb40e6eaaae4564c5c81b8b644bba3f7 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Thu, 27 Mar 2003 23:02:43 +0000 Subject: Doc updates from John + some minor fixes by me (This used to be commit 7fc49746dfd8d93066fe6870e3b642a5898aa032) --- docs/docbook/global.ent | 62 ++- docs/docbook/manpages/smbsh.1.sgml | 83 +--- docs/docbook/projdoc/CUPS-printing.sgml | 843 +++++++++++++++++++------------- docs/docbook/projdoc/ServerType.sgml | 1 + docs/docbook/projdoc/samba-doc.sgml | 2 + 5 files changed, 573 insertions(+), 418 deletions(-) (limited to 'docs/docbook') diff --git a/docs/docbook/global.ent b/docs/docbook/global.ent index 018d29a6a8..659c448ed1 100644 --- a/docs/docbook/global.ent +++ b/docs/docbook/global.ent @@ -96,6 +96,66 @@ never removed by the client. &stdarg.logfile; '> + +-R <name resolve order> +This option is used to determine what naming +services and in what order to resolve +host names to IP addresses. The option takes a space-separated +string of different name resolution options. + +The options are: "lmhosts", "host", "wins" and "bcast". +They cause names to be resolved as follows : + + +lmhosts: +Lookup an IP address in the Samba lmhosts file. If the +line in lmhosts has no name type attached to the +NetBIOS name +(see the lmhosts + 5 for details) +then any name type matches for lookup. + + +host: +Do a standard host name to IP address resolution, using +the system /etc/hosts, NIS, or DNS +lookups. This method of name resolution is operating +system dependent, for instance on IRIX or Solaris this +may be controlled by the /etc/nsswitch.conf + file). Note that this method is only used +if the NetBIOS name type being queried is the 0x20 +(server) name type, otherwise it is ignored. + + +wins: +Query a name with the IP address listed in the +wins server parameter. If no +WINS server has been specified this method will be +ignored. + + +bcast: +Do a broadcast on each of the known local interfaces +listed in the interfaces +parameter. This is the least reliable of the name +resolution methods as it depends on the target host +being on a locally connected subnet. + + + +If this parameter is not set then the name resolve order +defined in the smb.conf +5 file parameter +(name resolve order) will be used. + +The default order is lmhosts, host, wins, bcast. Without +this parameter or any entry in the name resolve order + parameter of the smb.conf +5 file, the name resolution methods +will be attempted in this order. +'> + -n <primary NetBIOS name> @@ -109,8 +169,6 @@ line setting will take precedence over settings in 5. '> - - -i <scope> diff --git a/docs/docbook/manpages/smbsh.1.sgml b/docs/docbook/manpages/smbsh.1.sgml index af080c298c..5a53c53be3 100644 --- a/docs/docbook/manpages/smbsh.1.sgml +++ b/docs/docbook/manpages/smbsh.1.sgml @@ -70,87 +70,8 @@ - - -R <name resolve order> - This option is used to determine what naming - services and in what order to resolve - host names to IP addresses. The option takes a space-separated - string of different name resolution options. - - The options are: "lmhosts", "host", "wins" and "bcast". - They cause names to be resolved as follows : - - - lmhosts: - Lookup an IP address in the Samba lmhosts file. If the - line in lmhosts has no name type attached to the - NetBIOS name - (see the lmhosts - 5 for details) - then any name type matches for lookup. - - - host: - Do a standard host name to IP address resolution, using - the system /etc/hosts, NIS, or DNS - lookups. This method of name resolution is operating - system dependent, for instance on IRIX or Solaris this - may be controlled by the /etc/nsswitch.conf - file). Note that this method is only used - if the NetBIOS name type being queried is the 0x20 - (server) name type, otherwise it is ignored. - - - wins: - Query a name with the IP address listed in the - wins server parameter. If no - WINS server has been specified this method will be - ignored. - - - bcast: - Do a broadcast on each of the known local interfaces - listed in the interfaces - parameter. This is the least reliable of the name - resolution methods as it depends on the target host - being on a locally connected subnet. - - - - If this parameter is not set then the name resolve order - defined in the smb.conf - 5 file parameter - (name resolve order) will be used. - - The default order is lmhosts, host, wins, bcast. Without - this parameter or any entry in the name resolve order - parameter of the smb.conf - 5 file, the name resolution methods - will be attempted in this order. - - - - -d <debug level> - debug level is an integer from 0 to 10. - - The default value if this parameter is not specified - is zero. - - The higher this value, the more detail will be logged - about the activities of nmblookup - 1. At level - 0, only critical errors and serious warnings will be logged. - - - - - -l logfilename - If specified causes all debug messages to be - written to the file specified by logfilename - . If not specified then all messages will be - written tostderr. - - + &popt.common.samba; + &stdarg.resolve.order; -L libdir diff --git a/docs/docbook/projdoc/CUPS-printing.sgml b/docs/docbook/projdoc/CUPS-printing.sgml index bfd23e3c6c..a932127d94 100644 --- a/docs/docbook/projdoc/CUPS-printing.sgml +++ b/docs/docbook/projdoc/CUPS-printing.sgml @@ -64,13 +64,12 @@ do any print file format conversion work. The CUPS files that need to be correctly set for RAW mode printers to work are: - - /etc/cups/mime.types + /etc/cups/mime.types /etc/cups/mime.convs - + -Both contain entries that must be uncommented to allow RAW mode +Both contain entries that must be uncommented to allow RAW mode operation. @@ -78,17 +77,17 @@ operation. Firstly, to enable CUPS based printing from Samba the following options must be enabled in your smb.conf file [globals] section: - + printing = CUPS printcap = CUPS - + When these parameters are specified the print directives in smb.conf (as well as in samba itself) will be ignored because samba will directly interface with CUPS through it's application program interface (API) - so long as Samba has been compiled with CUPS library (libcups) support. If samba has NOT been compiled with CUPS support then -printing will use the System V AT&T command set with the -oraw +printing will use the System V AT&T command set with the -oraw option automatically passing through. @@ -103,16 +102,14 @@ at the time when the driver initially generated the PostScript data and CUPS in printer communication backend. - -NOTE: editing in the "mime.convs" and the "mime.types" file does not *enforce* -"raw" printing, it only *allows* it. - +NOTE: editing in the "mime.convs" and the "mime.types" file does not *enforce* +"raw" printing, it only *allows* it. Print files that arrive from MS Windows printing are "auto-typed" by CUPS. This aids the process of determining proper treatment while in the print queue system. - + Files generated by PCL drivers and directed at PCK printers get auto-typed as application/octet-stream. Unknown file format types also @@ -123,12 +120,12 @@ the process of determining proper treatment while in the print queue system. Files generated by a Postscript driver and directed at a Postscript printer are auto-typed depending on the auto-detected most suitable MIME type as: - + * application/postscript * application/vnd.cups-postscript - + - + @@ -160,7 +157,7 @@ or "cupsomatic" will take over (depending on the printer configuration, as determined by the PPD in use). - + A printer queue with *no* PPD associated to it is a "raw" printer and all files will go directly there as received by the spooler. The exeptions are file types "application/octet-stream" which need "passthrough feature" enabled. @@ -168,9 +165,9 @@ will go directly there as received by the spooler. The exeptions are file types CUPS backend. This backend is responsible for the sending of the data to the device (as in the "device URI" notation as lpd://, socket://, smb://, ipp://, http://, parallel:/, serial:/, usb:/ etc.) - + - + "cupsomatic"/Foomatic are *not* native CUPS drivers and they don't ship with CUPS. They are a Third Party add-on, developed at Linuxprinting.org. As such, they are a brilliant hack to make all models (driven by Ghostscript drivers/filters in @@ -191,7 +188,7 @@ This line persuades CUPS to hand the file to cupsomatic, once it has successfull converted it to the MIME type "application/vnd.cups-postscript". This conversion will not happen for Jobs arriving from Windows which are auto-typed "application/octet-stream", with the according changes in "/etc/cups/mime.types" in place. - + CUPS is widely configurable and flexible, even regarding its filtering mechanism. @@ -262,11 +259,11 @@ The following diagrams reveal how CUPS handles print jobs. # letters are FILE-FORMATS or MIME types, other are filters (this is # true for pre-1.1.15 of pre-4.3 versions of CUPS and ESP PrintPro): # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -291,7 +288,7 @@ The following diagrams reveal how CUPS handles print jobs. # | # | # V -# rasterto (f.e. Gimp-Print filters may be plugged in here) +# rastertosomething (f.e. Gimp-Print filters may be plugged in here) # | (= "raster driver") # | # V @@ -302,11 +299,11 @@ The following diagrams reveal how CUPS handles print jobs. # backend # # -# ESP PrintPro has some enhanced "rasterto" filters as compared to +# ESP PrintPro has some enhanced "rastertosomething" filters as compared to # CUPS, and also a somewhat improved "pstoraster" filter. # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ######################################################################### @@ -317,11 +314,11 @@ The following diagrams reveal how CUPS handles print jobs. # This is how "cupsomatic" comes into play: # ========================================= # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -341,11 +338,11 @@ The following diagrams reveal how CUPS handles print jobs. # | (= "postscipt interpreter") Ghostscript commandline # | to let the file be # V processed by a -# APPLICATION/VND.CUPS-RASTER "-sDEVICE=" +# APPLICATION/VND.CUPS-RASTER "-sDEVICE=s.th." # | call...) # | | # V | -# rasterto V +# rastertosomething V # | (= "raster driver") +-------------------------+ # | | Ghostscript at work.... | # V | | @@ -353,7 +350,7 @@ The following diagrams reveal how CUPS handles print jobs. # | | # | | # V | -# backend <------------------------------------+ +# backend >------------------------------------+ # | # | # V @@ -364,7 +361,7 @@ The following diagrams reveal how CUPS handles print jobs. # "APPLICATION/VND.CUPS-POSTSCRPT" stage and deviates it through # the CUPS-external, systemwide Ghostscript installation, bypassing the # "pstoraster" filter (therefor also bypassing the CUPS-raster-drivers -# "rasterto", and hands the rasterized file directly to the CUPS +# "rastertosomething", and hands the rasterized file directly to the CUPS # backend... # # cupsomatic is not made by the CUPS developers. It is an independent @@ -372,7 +369,7 @@ The following diagrams reveal how CUPS handles print jobs. # Linuxprinting.org. (see also http://www.cups.org/cups-help.html) # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ######################################################################### @@ -383,11 +380,11 @@ The following diagrams reveal how CUPS handles print jobs. # And this is how it works for ESP PrintPro from 4.3: # =================================================== # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -411,7 +408,7 @@ The following diagrams reveal how CUPS handles print jobs. # | # | # V -# rasterto (f.e. Gimp-Print filters may be plugged in here) +# rastertosomething (f.e. Gimp-Print filters may be plugged in here) # | (= "raster driver") # | # V @@ -422,7 +419,7 @@ The following diagrams reveal how CUPS handles print jobs. # backend # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ######################################################################### @@ -434,11 +431,11 @@ The following diagrams reveal how CUPS handles print jobs. # ================================================================ # # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -458,11 +455,11 @@ The following diagrams reveal how CUPS handles print jobs. # | (= "postscipt interpreter") Ghostscript commandline # | to let the file be # V processed by a -# APPLICATION/VND.CUPS-RASTER "-sDEVICE=" +# APPLICATION/VND.CUPS-RASTER "-sDEVICE=s.th." # | call...) # | | # V | -# rasterto V +# rastertosomething V # | (= "raster driver") +-------------------------+ # | | Ghostscript at work.... | # V | | @@ -470,14 +467,14 @@ The following diagrams reveal how CUPS handles print jobs. # | | # | | # V | -# backend <------------------------------------+ +# backend >------------------------------------+ # | # | # V # THE PRINTER # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ######################################################################### @@ -488,11 +485,11 @@ The following diagrams reveal how CUPS handles print jobs. # And this is how it works for CUPS from 1.1.15: # ============================================== # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -517,11 +514,11 @@ The following diagrams reveal how CUPS handles print jobs. # +------------------v------------------------------+ # | # | -# APPLICATION/VND.CUPS-RASTER <-------+ +# APPLICATION/VND.CUPS-RASTER >-------+ # | # | # V -# rasterto +# rastertosomething # | (= "raster driver") # | # V @@ -538,14 +535,14 @@ The following diagrams reveal how CUPS handles print jobs. # "gs -h" needs to show up a "cups" device. pstoraster is now a # calling an appropriate "gs -sDEVICE=cups..." commandline to do # the job. It will output "application/vnd.cup-raster", which will -# be finally processed by a CUPS raster driver "rasterto" +# be finally processed by a CUPS raster driver "rastertosomething" # Note the difference to "cupsomatic", which will *not* output # CUPS-raster, but a final version of the printfile, ready to be # sent to the printer. cupsomatic also doesn't use the "cups" # devicemode in Ghostscript, but one of the classical devicemodes.... # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ######################################################################### @@ -556,11 +553,11 @@ The following diagrams reveal how CUPS handles print jobs. # And this is how it works for CUPS from 1.1.15, with cupsomatic included: # ======================================================================== # -# -FILEFORMAT +# SOMETHNG-FILEFORMAT # | # | # V -# tops +# somethingtops # | # | # V @@ -577,7 +574,7 @@ The following diagrams reveal how CUPS handles print jobs. # +------------------v------------------------------+ # | Ghostscript . Ghostscript at work.... | # | at work... . (with "-sDEVICE= | -# | (with . " | +# | (with . s.th." | # | "-sDEVICE=cups") . | # | . | # | (CUPS standard) . (cupsomatic) | @@ -587,15 +584,15 @@ The following diagrams reveal how CUPS handles print jobs. # +------------------v--------------v---------------+ # | | # | | -# APPLICATION/VND.CUPS-RASTER <-------+ | +# APPLICATION/VND.CUPS-RASTER >-------+ | # | | # | | # V | -# rasterto | +# rastertosomething | # | (= "raster driver") | # | | # V | -# SOMETHING-DEVICE-SPECIFIC <------------------------+ +# SOMETHING-DEVICE-SPECIFIC >------------------------+ # | # | # V @@ -603,7 +600,7 @@ The following diagrams reveal how CUPS handles print jobs. # # # NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to -# CUPS and ESP PrintPro plug-in where rasterto is noted. +# CUPS and ESP PrintPro plug-in where rastertosomething is noted. # ########################################################################## @@ -618,161 +615,196 @@ The following diagrams reveal how CUPS handles print jobs. CUPS ships with good support for HP LaserJet type printers. You can install the driver as follows: - + lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd - + (The "-m" switch will retrieve the "laserjet.ppd" from the standard repository for not-yet-installed-PPDs, which CUPS typically stores in -filename>/usr/share/cups/model. Alternatively, you may use +/usr/share/cups/model. Alternatively, you may use "-P /absolute/filesystem/path/to/where/there/is/PPD/your.ppd"). - - -Windows printing involves some more steps.... - -But let me first point out some more general things about printer "drivers" -for Linux/Unix (yes, and for Mac OS X now!), be it you use CUPS or one of -the venerable (I'd even call them "ancient" and "rusty" now...) printing -systems. + +Further printing steps -You -- and everybody else, for that matter -- should always also consult the -database on linuxprinting.org for all recommendations about "which driver -is best used for which printer": + +Always also consult the database on linuxprinting.org for all recommendations +about which driver is best used for each printer: + - http://www.linuxprinting.org/printer_list.cgi +http://www.linuxprinting.org/printer_list.cgi + There select your model and click on "Show". You'll arrive at a page listing -all drivers working with your model. There will always be *one* "recommended" -one. Try this one first. In your case ("HP LaserJet 4 Plus"), you'll arrive -here: +all drivers working with your model. There will always be *one* +recommended one. Try this one first. In your case +("HP LaserJet 4 Plus"), you'll arrive here: + - http://www.linuxprinting.org/show_printer.cgi?recnum=75104 +http://www.linuxprinting.org/show_printer.cgi?recnum=75104 + The recommended driver is "ljet4". It has a link to the page for the ljet4 driver too: + - http://www.linuxprinting.org/show_driver.cgi?driver=ljet4 +http://www.linuxprinting.org/show_driver.cgi?driver=ljet4 -On the driver's page, you'll find various important and detailed infos about -how to use that driver within various spoolers. You can generate a PPD for + +On the driver's page, you'll find important and detailed info about how to use +that driver within the various available spoolers. You can generate a PPD for CUPS. The PPD contains all the info about how to use your model and the driver; this is, once installed, working transparently for the user -- you'll only need to choose resolution, paper size etc. from the web-based menu or from the print dialog GUI or from the commandline... + + On the driver's page, choose to use the "PPD-O-Matic" online PPD generator program. Select your model and click "Generate PPD file". When you safe the -appearing ASCII text file, don't use "cut'n'past" (as it will possible corrupt +appearing ASCII text file, don't use "cut'n'past" (as it could possiblly corrupt line endings and tabs), but use "Save as..." in your browser's menu. Save it at "/some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd" + + Then install the printer: - + + "lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -P /some/path/on/your/filesystem/somewhere/my-name-for-my-printer.ppd" + + Note, that for all the "Foomatic-PPDs" from Linuxprinting.org, you also need a special "CUPS filter" named "cupsomatic". Get the latest version of -"cupsomatic" from +"cupsomatic" from: + - http://www.linuxprinting.org/cupsomatic +http://www.linuxprinting.org/cupsomatic -This needs to be copied to "/usr/lib/cups/filter/cupsomatic" and be made world -executable. This filter is needed to read and act upon the specially encoded -Foomatic comments, embedded in the printfile, which in turn are used to -construct (transparently for you, the user) the complicated ghostscript command -line needed for your printer/driver combo. + +This needs to be copied to /usr/lib/cups/filter/cupsomatic +and be made world executable. This filter is needed to read and act upon the +specially encoded Foomatic comments, embedded in the printfile, which in turn +are used to construct (transparently for you, the user) the complicated +ghostscript command line needed for your printer/driver combo. + + You can have a look at all the options for the Ghostscript commandline supported by your printer and the ljet4 driver by going to the section "Execution details", selecting your model (Laserjet 4 Plus) and clicking on "Show execution details". This will bring up this web page: + - http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details +http://www.linuxprinting.org/execution.cgi?driver=ljet4&printer=75104&.submit=Show+execution+details -The ingenious thing is this: the database is kept very current. If there + +The ingenious thing is that the database is kept current. If there is a bug fix and an improvement somewhere in the database, you will always get the most current and stable and feature-rich driver by following -the steps described above... Till Kamppeter from MandrakeSoft is doing an -excellent job here, and too few people still know about it. (So if you use -it often, please send him a note of your appreciation sometime...) +the steps described above. + -(The latest and greatest improvement now is support for "custom page sizes" -for all those printers which support it...) + +Till Kamppeter from MandrakeSoft is doing an excellent job here that too few +people are aware of. (So if you use it often, please send him a note showing +your appreciation). + +The latest and greatest improvement now is support for "custom page sizes" +for all those printers which support it. + + + "cupsomatic" is documented here: + - http://www.linuxprinting.org/cups-doc.html +http://www.linuxprinting.org/cups-doc.html + More printing tutorial info may be found here: + - http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/ +http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/ + Note, that *all* the Foomatic drivers listed on Linuxprinting.org (now approaching the "all-time high" number of 1.000 for the supported models) are using a special filtering chain involving Ghostscript, as described -in great detail in the Samba CVS sources (for 2.2.x) in +in this document. + - docs/textdocs/CUPS-PrintingInfo.txt + +Summary - You need: + -To sum it up: + + -* having a "foomatic+" PPD is not enough to print with CUPS - (but it is *one* important component) -* you also need the "cupsomatic" filter script (Perl) in "/usr/lib/cups/filters/" -* you need Perl to make cupsomatic run -* you also need Ghostscript (because it is called and controlled by the - PPD/cupsomatic combo in a way to fit your printermodel/driver combo...) -* your Ghostscript *must*, depending on the driver/model, contain support - for a certain "device" (as shown by "gs -h") + A "foomatic+something" PPD is not enough to print with CUPS (but it is *one* important component) + The "cupsomatic" filter script (Perl) in /usr/lib/cups/filters/ + Perl to make cupsomatic run + Ghostscript (because it is called and controlled by the PPD/cupsomatic combo in a way to fit your printermodel/driver combo. + Ghostscript *must*, depending on the driver/model, contain support for a certain "device" (as shown by "gs -h") + + In the case of the "hpijs" driver, you need a Ghostscript version, which -is showing a "ijs" amongst its supported devices in "gs -h". In the case of +has "ijs" amongst its supported devices in "gs -h". In the case of "hpijs+foomatic", a valid ghostscript commandline would be reading like this: + + gs -q -dBATCH -dPARANOIDSAFER -dQUIET -dNOPAUSE -sDEVICE=ijs \ - -sIjsServer=hpijs -dDuplex= \ - -r,PS:MediaPosition= -dIjsUseOutputFD \ + -sIjsServer=hpijsPageSize -dDuplex=Duplex Model \ + -rResolution,PS:MediaPosition=InputSlot -dIjsUseOutputFD \ -sOutputFile=- - + + Note, that with CUPS and the "hpijs+foomatic" PPD (plus Perl and cupsomatic) you don't need to remember this. You can choose the available print options thru a GUI print command (like "glp" from ESP's commercially supported PrintPro software, or KDE's "kprinter", or GNOME's "gtklp" or the independent "xpp") or the CUPS web interface via human-readable drop-down selection -menus..... +menus. + + If you use "ESP Ghostscript" (also under the GPL, provided by Easy Software -Products, the makers of CUPS, downloadable from http://www.cups.org/software.html, +Products, the makers of CUPS, downloadable from +http://www.cups.org/software.html, co-maintained by the developers of linuxprinting.org), you are guaranteed to have in use the most uptodate, bug-fixed, enhanced and stable version of a Free Ghostscript. It contains support for ~300 devices, whereas plain vanilla -GNU Ghostscript 7.05 only has ~200.... - ->>/ However, I can only print a Cups test page, from the web interface. when I -/>>/ try to print a windows test page, it acts like the job was never sent. -/ - * Can you print "standard" jobs from the CUPS machine? +GNU Ghostscript 7.05 only has ~200. + - * Are the jobs from Windows visible in the Web interface on CUPS - (http://localhost:631/)? + +If you print only one CUPS test page, from the web interface and when you try to +print a windows test page, it acts like the job was never sent: -*Most important:* What kind of printer driver are you using on the Windows clients??? + + Can you print "standard" jobs from the CUPS machine? + Are the jobs from Windows visible in the Web interface on CUPS (http://localhost:631/)? + Most important: What kind of printer driver are you using on the Windows clients? + You can try to get a more detailed debugging info by setting "LogLevel debug" in -"/etc/cups/cupsd.conf", re-start cupsd and investigate "/var/log/cups/error_log" +/etc/cups/cupsd.conf, re-start cupsd and investigate /var/log/cups/error_log for the whereabouts of your Windows-originating printjobs: - - * what does the "auto-typing" line say? which is the "MIME type" CUPS thinks - is arriving from the Windows clients? - * are there "filter" available for this MIME type? - * are there "filter rules" defined in "/etc/cups/mime.convs" for this MIME type? - + + what does the "auto-typing" line say? which is the "MIME type" CUPS thinks is arriving from the Windows clients? + are there "filter" available for this MIME type? + are there "filter rules" defined in "/etc/cups/mime.convs" for this MIME type? + + @@ -780,17 +812,22 @@ for the whereabouts of your Windows-originating printjobs: Limiting the number of pages users can print -The feature you want is dependent on the real print subsystem -you're using. Samba's part is always to receive the job files -from the clients (filtered *or* unfiltered) and hand it over -to this printing subsystem. +The feature you want is dependent on the real print subsystem you're using. +Samba's part is always to receive the job files from the clients (filtered +*or* unfiltered) and hand it over to this printing subsystem. + + Of course one could "hack" things with one's own scripts. + + But there is CUPS (Common Unix Printing System). CUPS supports "quotas". Quotas can be based on sizes of jobs or on the number of pages or both, and are spanning any time period you want. + + This is an example command how root would set a print quota in CUPS, assuming an existing printer named "quotaprinter": @@ -802,20 +839,22 @@ assuming an existing printer named "quotaprinter": This would limit every single user to print 100 pages or 1024 KB of data (whichever comes first) within the last 604.800 seconds ( = 1 week). + -For CUPS to count correctly, the printfile needs to pass the CUPS -"pstops" filter, otherwise it uses a "dummy" count of "1". (Some -printfiles don't pass it -- f.e. image files -- but then those are -mostly 1 page jobs anyway). This also means, proprietary drivers for -the target printer running on the client computers and CUPS/Samba -then spooling these files as "raw" (i.e. leaving them untouched, not + +For CUPS to count correctly, the printfile needs to pass the CUPS "pstops" filter, +otherwise it uses a "dummy" count of "1". Some printfiles don't pass it +(eg: image files) but then those are mostly 1 page jobs anyway. This also means, +proprietary drivers for the target printer running on the client computers and +CUPS/Samba then spooling these files as "raw" (i.e. leaving them untouched, not filtering them), will be counted as "1-pagers" too! + -You need to send PostScript from the clients (i.e. run a PostScript -driver there) for having the chance to get accounting done. If the -printer is a non-PostScript model, you need to let CUPS do the job to -convert the file to a print-ready format for the target printer. This -will be working for currently ~1.000 different printer models, see + +You need to send PostScript from the clients (i.e. run a PostScript driver there) +for having the chance to get accounting done. If the printer is a non-PostScript model, +you need to let CUPS do the job to convert the file to a print-ready format for the +target printer. This will be working for currently ~1.000 different printer models, see @@ -830,125 +869,178 @@ not counted correctly (the reason is that it often --- depending on the "PPD" being used --- did write a "PJL"-header in front of the real PostScript which made CUPS to skip the pstops and go directy to the "pstoraster" stage). + - From CUPS-1.1.16 onward you can use the "CUPS PostScript Driver + +From CUPS-1.1.16 onward you can use the "CUPS PostScript Driver for Windows NT/2K/XP clients" (it is tagged in the download area of http://www.cups.org/ as the "cups-samba-1.1.16.tar.gz" package). -It is *not* working for Win9x/ME clients. But it.... +It is *not* working for Win9x/ME clients. But it: + - ...it guarantees to not write an PJL-header; - ...it guarantees to still read and support all PJL-options named - in the driver PPD with its own means; - ...it guarantees the file going thru the "pstops" filter on the - CUPS/Samba server; - ...it guarantees to page-count correctly the printfile... + + >it guarantees to not write an PJL-header + it guarantees to still read and support all PJL-options named in the driver PPD with its own means + it guarantees the file going thru the "pstops" filter on the CUPS/Samba server + it guarantees to page-count correctly the printfile + + You can read more about the setup of this combination in the manpage for "cupsaddsmb" (only present with CUPS installed, only current with CUPS 1.1.16). + -These are the items CUPS logs in the "page_log" for every single -*page* of a job: + +These are the items CUPS logs in the "page_log" for every single *page* of a job: + -* Printer name -* User name -* Job ID -* Time of printing -* the page number -* the number of copies -* a billing info string (optional) + + * Printer name + * User name + * Job ID + * Time of printing + * the page number + * the number of copies + * a billing info string (optional) + + Here is an extract of my CUPS server's page_log file to illustrate the format and included items: + -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 1 2 #marketing -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 2 2 #marketing -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 3 2 #marketing -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 4 2 #marketing -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 5 2 #marketing -infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 6 2 #marketing - -This was Job ID "40", printed on "infotec_IS2027" by user "kurt", -a 6-page job printed in 2 copies and billed to "#marketing"... - -Which flaws or shortcomings are there? - - * the ones named above; - * CUPS really counts the job pages being *processsed in software* - (going thru the "RIP") rather than the physical sheets successfully - leaving the printing device -- if there is a jam while printing - the 5th sheet out of 1000 and the job is aborted by the printer, - the "page count" will still show the figure of 1000 for that - job; - * all quotas are the same for all users (no flexibility to - give the boss a higher quota than the clerk) - * no support for groups; - * no means to read out the current balance or "used-up" - number of current quota; - * a user having used up 99 sheets of 100 quota will still be - able to send and print a 1.000 sheet job; - * a user being denied a job because of a filled-up quota - doesn't get a meaningful error message from CUPS other than - "client-error-not-possible". + + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 1 2 #marketing + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 2 2 #marketing + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 3 2 #marketing + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 4 2 #marketing + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 5 2 #marketing + infotec_IS2027 kurt 40 [22/Nov/2002:13:18:03 +0100] 6 2 #marketing + + +This was Job ID "40", printed on "infotec_IS2027" by user "kurt", a 6-page job +printed in 2 copies and billed to "#marketing"... + + + +What flaws or shortcomings are there? + + + + the ones named above + + + CUPS really counts the job pages being *processsed in software* + (going thru the "RIP") rather than the physical sheets successfully + leaving the printing device -- if there is a jam while printing + the 5th sheet out of 1000 and the job is aborted by the printer, + the "page count" will still show the figure of 1000 for that job + + + + all quotas are the same for all users (no flexibility to give the + boss a higher quota than the clerk) no support for groups + + + + no means to read out the current balance or "used-up" number of current quota + + + + a user having used up 99 sheets of 100 quota will still be able to send and print a 1.000 sheet job + + + + a user being denied a job because of a filled-up quota doesn't get a meaningful + error message from CUPS other than "client-error-not-possible". + + + + But this is the best system out there currently. And there are huge improvements under development: + ---> page counting will go into the "backends" (these talk directly - to the printer and will increase the count in sync with the - actual printing process -- a jam at the 5th sheet will lead - to a stop in the counting...) + + page counting will go into the "backends" (these talk + directly to the printer and will increase the count in sync with the + actual printing process -- a jam at the 5th sheet will lead to a stop in the counting) ---> quotas will be handled more flexibly; + quotas will be handled more flexibly ---> probably there will be support for users to inquire their - "accounts" in advance; + probably there will be support for users to inquire their "accounts" in advance ---> probably there will be support for some other tools around - this topic... + probably there will be support for some other tools around this topic + + Other than the current stage of the CUPS development, I don't know any other ready-to-use tool which you could consider. -You can download the driver files from http://www.cups.org/software.html. It -is a separate package from the CUPS base software files, tagged as "CUPS 1.1.16 +You can download the driver files from +http://www.cups.org/software.html. +It is a separate package from the CUPS base software files, tagged as "CUPS 1.1.16 Windows NT/2k/XP Printer Driver for SAMBA (tar.gz, 192k)". The filename to download is "cups-samba-1.1.16.tar.gz". Upon untar-/unzip-ping it will reveal -the files +the files: + + + cups-samba.install cups-samba.license cups-samba.readme cups-samba.remove cups-samba.ss + + + These have been packaged with the ESP meta packager software "EPM". The *.install and *.remove files are simple shell script, which untars the *.ss (which is nothing else than a tar-archive) and puts its contents -into "/usr/share/cups/drivers/". Its contents are 3 files: +into /usr/share/cups/drivers/. Its contents are 3 files: + + + cupsdrvr.dll cupsui.dll cups.hlp + + -[ ATTENTION: due to a bug the current release puts the "cups.hlp" into - "/usr/share/drivers/" instead of "/usr/share/cups/drivers/". To work - around this, copy/move the file after running the "./cups-samba.install" - script manually to the right place: + +ATTENTION: due to a bug one CUPS release puts the cups.hlp +into /usr/share/drivers/ instead of +/usr/share/cups/drivers/. To work around this, copy/move +the file after running the "./cups-samba.install" script manually to the right place: + - "cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/" ] + + + cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/ + + + -This new CUPS PostScript driver is currently binary-only, but free (as in -free beer); no source code is provided (yet). The reason is this: it has + + +This new CUPS PostScript driver is currently binary-only, but free +no source code is provided (yet). The reason is this: it has been developed with the help of the Microsoft Driver Developer Kit (DDK) and compiled with Microsoft Visual Studio 6. It is not clear to the driver developers if they are allowed to distribute the whole of the source code as Free Software. However, they will likely release the "diff" in source code under the GPL, so anybody with a license of Visual Studio and a DDK will be able to compile for him/herself. + + Once you have run the install script (and possibly manually moved the "cups.hlp" file to "/usr/share/cups/drivers/"), the driver is ready to be put into Samba's [print$] share (which often maps to "/etc/samba/drivers/" @@ -958,145 +1050,186 @@ put root into the smbpasswd file by running "smbpasswd" should you run this whole procedure for the first time.] Once the driver files are in the [print$] share, they are ready to be downloaded and installed by the Win NT/2k/XP clients. + + + NOTE 1: Win 9x/ME clients won't work with this driver. For these you'd - still need to use the ADOBE*.* drivers as previously. +still need to use the ADOBE*.* drivers as previously. + + NOTE 2: It is not harming if you've still the ADOBE*.* driver files from - previous installations in the "/usr/share/cups/drivers/" directory. - The new cupsaddsmb (from 1.1.16) will automatically use the - "newest" installed driver (which here then is the CUPS drivers). +previous installations in the "/usr/share/cups/drivers/" directory. +The new cupsaddsmb (from 1.1.16) will automatically use the +"newest" installed driver (which here then is the CUPS drivers). + + NOTE 3: Should your Win clients have had the old ADOBE*.* files and the - Adobe PostScript drivers installed, the download and installation - of the new CUPS PostScript driver for Windows NT/2k/XP will fail - at first. - It is not enough to "delete" the printer (as the driver files - will still be kept by the clients and re-used if you try to - re-install the printer). To really get rid of the Adobe driver - files on the clients, open the "Printers" folder (possibly via - "Start --> Settings --> Control Panel --> Printers"), right-click - onto the folder background and select "Server Properties". A - new dialog opens; select the "Drivers" tab; on the list select - the driver you want to delete and click on the "Delete" button. - (This will only work if there is no single printer left which - uses that particular driver -- you need to "delete" all printers - using this driver in the "Printers" folder first...) - -NOTE 4: Once you have successfully downloaded the CUPS PostScript driver - to a client, you can easily switch all printers to this one - by proceeding as described elsewhere in the "Samba HOWTO - Collection" to change a driver for an existing printer.... +Adobe PostScript drivers installed, the download and installation +of the new CUPS PostScript driver for Windows NT/2k/XP will fail +at first. + + +It is not enough to "delete" the printer (as the driver files +will still be kept by the clients and re-used if you try to +re-install the printer). To really get rid of the Adobe driver +files on the clients, open the "Printers" folder (possibly via +"Start --> Settings --> Control Panel --> Printers"), right-click +onto the folder background and select "Server Properties". A +new dialog opens; select the "Drivers" tab; on the list select +the driver you want to delete and click on the "Delete" button. +(This will only work if there is no single printer left which +uses that particular driver -- you need to "delete" all printers +using this driver in the "Printers" folder first.) + + + +Once you have successfully downloaded the CUPS PostScript driver +to a client, you can easily switch all printers to this one +by proceeding as described elsewhere in the "Samba HOWTO +Collection" to change a driver for an existing printer. + + What are the benefits with the "CUPS PostScript driver for Windows NT/2k/XP" as compared to the Adobe drivers? - 9 -* no hassle with the Adobe EULA; no hassle with the question "where do I - get the ADOBE*.* driver files from?" - -* the Adobe drivers (depending on the printer PPD associated with them) - often put a PJL header in front of the core PostScript part of the print - file (thus the file starts with "<1B>%-12345X" or "%-12345X" - instead of "%!PS"). This leads to the CUPS daemon autotyping the - arriving file as a print-ready file, not requiring a pass thru the - "pstops" filter (to speak more technical, it is not regarded as the - generic MIME type "application/postscript", but as the more special - MIME type "application/cups.vnd-postscript"), which therefore also - leads to the page accounting in "/var/log/cups/page_log" not receiving - the exact mumber of pages; instead the dummy page number of "1" is - logged in a standard setup...) - -* the Adobe driver has more options to "mis-configure" the PostScript - generated by it (like setting it inadvertedly to "Optimize for Speed", - instead of "Optimize for Portability", which could lead to CUPS being - unable to process it....) - -* the CUPS PostScript driver output sent by Windows clients to the CUPS - server will be guaranteed to be auto-typed as generic MIME type - "application/postscript", thusly passing thru the CUPS "pstops" filter - and logging the correct number of pages in the page_log for accounting - and quota purposes... - -* the CUPS PostScript driver supports the sending of additional print - options by the Win NT/2k/XP clients, such as naming the CUPS standard - banner pages (or the custom ones, should they be installed at the time - of driver download), using the CUPS "page-label" option, setting a - job-priority and setting the scheduled time of printing (with the option - to support additional useful IPP job attributes in the future). - -* the CUPS PostScript driver supports the inclusion of the new - "*cupsJobTicket" comments at the beginnig of the PostScript file (which - could be used in the future for all sort of beneficial extensions on - the CUPS side, but which will not disturb any other application as those - will regard it as a comment and simply ignore it). - -* the CUPS PostScript driver will be the heart of the fully fledged CUPS - IPP client for Windows NT/2k/XP to be released soon (probably alongside - the first Beta release for CUPS 1.2). + + + + + no hassle with the Adobe EULA + + + + no hassle with the question "where do I get the ADOBE*.* driver files from?" + + + the Adobe drivers (depending on the printer PPD associated with them) + often put a PJL header in front of the core PostScript part of the print + file (thus the file starts with "1B%-12345X" or "escape%-12345X" + instead of "%!PS"). This leads to the CUPS daemon autotyping the + arriving file as a print-ready file, not requiring a pass thru the + "pstops" filter (to speak more technical, it is not regarded as the + generic MIME type "application/postscript", but as the more special + MIME type "application/cups.vnd-postscript"), which therefore also + leads to the page accounting in "/var/log/cups/page_log" not receiving + the exact mumber of pages; instead the dummy page number of "1" is + logged in a standard setup) + + + + the Adobe driver has more options to "mis-configure" the PostScript + generated by it (like setting it inadvertedly to "Optimize for Speed", + instead of "Optimize for Portability", which could lead to CUPS being + unable to process it) + + + + the CUPS PostScript driver output sent by Windows clients to the CUPS + server will be guaranteed to be auto-typed as generic MIME type + "application/postscript", thusly passing thru the CUPS "pstops" filter + and logging the correct number of pages in the page_log for accounting + and quota purposes + + + + the CUPS PostScript driver supports the sending of additional print + options by the Win NT/2k/XP clients, such as naming the CUPS standard + banner pages (or the custom ones, should they be installed at the time + of driver download), using the CUPS "page-label" option, setting a + job-priority and setting the scheduled time of printing (with the option + to support additional useful IPP job attributes in the future). + + + + the CUPS PostScript driver supports the inclusion of the new + "*cupsJobTicket" comments at the beginnig of the PostScript file (which + could be used in the future for all sort of beneficial extensions on + the CUPS side, but which will not disturb any other application as those + will regard it as a comment and simply ignore it). + + + + the CUPS PostScript driver will be the heart of the fully fledged CUPS + IPP client for Windows NT/2k/XP to be released soon (probably alongside + the first Beta release for CUPS 1.2). + + + + Advanced Postscript Printing from MS Windows -* Let the Windows Clients use a PostScript driver, to produce - PostScript as their print output sent towards the Samba print - server (just like any Linux or Unix Client would also use - PostScript to send to the server...) +Let the Windows Clients use a PostScript driver to deliver poistscript to +the samba print server (just like any Linux or Unix Client would also use +PostScript to send to the server) + -* make the Unix printing subsystem which is underneath Samba - convert the incoming PostScript files to the native print - format of the target printers (would likely be PCL? - I understand you have mainly HP models?) + +Make the Unix printing subsystem to which Samba sends the job convert the +incoming PostScript files to the native print format of the target printers +(would be PCL if you have an HP printer) + -* You're afraid, that this would just mean a *Generic* PostScript - driver for the clients? With no Simplex/Duplex selection, - no paper tray choice? But you need them to be able to set up - their jobs, ringing all the bells and whistles of the printers? + +Now if you are afraid that this would just mean using a *Generic* PostScript +driver for the clients that has no Simplex/Duplex selection, and no paper tray +choice, but you need them to be able to set up print jobs, with all the bells +and whistles of your printers:- + - --> Not possible with traditional spooling systems! + + Not possible with traditional spooling systems - --> But perfectly supported by CUPS (which uses "PPD" files to - describe how to control the print options for PostScript and - non-PostScript devices alike... + + But perfectly supported by CUPS (which uses "PPD" files to + describe how to control the print options for PostScript and + non-PostScript devices alike... + + - CUPS PPDs are working perfectly on Windows - clients who use Adobe PostScript drivers (or the new CUPS - PostScript driver for Windows NT/2K/XP). Clients can use - them to setup the job to their liking and CUPS will use - the received job options to make the (PCL-, ESC/P- or - PostScript-) printer behave as required. + +CUPS PPDs are working perfectly on Windows clients who use Adobe PostScript +drivers (or the new CUPS PostScript driver for Windows NT/2K/XP). Clients can use +them to setup the job to their liking and CUPS will use the received job options +to make the (PCL-, ESC/P- or PostScript-) printer behave as required. + -* You want to have the additional benefit of page count logging - and accounting? In this case the CUPS PostScript driver - is the best choice (better than the Adobe one). + +If you want to have the additional benefit of page count logging and accounting +then the CUPS PostScript driver is the best choice (better than the Adobe one). + -* You want to make the drivers downloadable for the clients? - "cupsaddsmb" is your friend. It will setup the [print$] - share on the Samba host to be ready to serve the clients - for a "point and print" driver installation... + +If you want to make the drivers downloadable for the clients then "cupsaddsmb" is +your friend. It will setup the [print$] share on the Samba host to be ready to serve +the clients for a "point and print" driver installation. + -"What strings are attached?", I hear you asking... + +What strings are attached? -You are right, there are some. But, given the sheer CPU power -you can buy nowadays in German supermarkets, these can be -overcome easily. + +There are some. But, given the sheer CPU power you can buy nowadays, +these can be overcome easily. The strings: + -The strings: Well, if the -CUPS/Samba side will have to print a *lot* onto 40 printers -serving 500 users, you probably will need to set up a second -server (which can do automatic load balancing with the first -one, plus a degree of fail-over mechanism). Converting the -incoming PostScript jobs, "interpreting" them for -non-PostScript printers, amounts to the work of a "RIP" -(Raster Image Processor) done in software. This requires -more CPU and RAM than for the mere "raw spooling" task -your current setup is solving... It all depends on the -avarage and peak printing load the server should be -able to handle.... + +Well, if the CUPS/Samba side will have to print to many printers serving many users, +you probably will need to set up a second server (which can do automatic load balancing +with the first one, plus a degree of fail-over mechanism). Converting the incoming +PostScript jobs, "interpreting" them for non-PostScript printers, amounts to the work +of a "RIP" (Raster Image Processor) done in software. This requires more CPU and RAM +than for the mere "raw spooling" task your current setup is solving. It all depends +on the avarage and peak printing load the server should be able to handle. @@ -1105,37 +1238,49 @@ able to handle.... Auto-Deletion of CUPS spool files -Samba print files pass thru 2 -different "spool" directories. Once the incoming directory -managed by Samba, (set f.e. in the "path = /var/spool/samba" -directive in the [printers] section of "smb.conf"). Second is -the spool directory of your UNIX print subsystem. For CUPS it is -normally "/var/spool/cups/", as set by the cupsd.conf directive +Samba print files pass thru two "spool" directories. One the incoming directory +managed by Samba, (set eg: in the "path = /var/spool/samba" directive in the [printers] +section of "smb.conf"). Second is the spool directory of your UNIX print subsystem. +For CUPS it is normally "/var/spool/cups/", as set by the cupsd.conf directive "RequestRoot /var/spool/cups". + -I am not sure, which one of your directories keeps the files. - From what you say, it is most likely the Samba part. + +I am not sure, which one of your directories keeps the files. From what you say, +it is most likely the Samba part. + + For the CUPS part, you may want to consult: + + http://localhost:631/sam.html#PreserveJobFiles and http://localhost:631/sam.html#PreserveJobHistory and http://localhost:631/sam.html#MaxJobs + -There are the settings described for your CUPS daemon, which -could lead to completed job files not being deleted. + +There are the settings described for your CUPS daemon, which could lead to completed +job files not being deleted. + + "PreserveJobHistory Yes" -- keeps some details of jobs in cupsd's mind (well it keeps the "c12345", "c12346" etc. files in the CUPS spool directory, which do a similar job as the old-fashioned BSD-LPD control files). This is set to "Yes" as a default. + + "PreserveJobFiles Yes" -- keeps the job files themselves in cupsd's mind (well it keeps the "d12345", "d12346" etc. files in the CUPS spool directory...). This is set to "No" as the CUPS default. + + "MaxJobs 500" -- this directive controls the maximum number of jobs that are kept in memory. Once the number of jobs reaches the limit, the oldest completed job is automatically @@ -1143,42 +1288,70 @@ purged from the system to make room for the new one. If all of the known jobs are still pending or active then the new job will be rejected. Setting the maximum to 0 disables this functionality. The default setting is 0. + + (There are also additional settings for "MaxJobsPerUser" and "MaxJobsPerPrinter"...) + -For everything to work as announced, you need to have three -things: + +For everything to work as announced, you need to have three things: + + + - * a Samba-smbd which is compiled against "libcups" (Check - on Linux by running "ldd `which smbd`") + + a Samba-smbd which is compiled against "libcups" (Check on Linux by running "ldd `which smbd`") + - * a Samba-smb.conf setting of "printing = cups" + + a Samba-smb.conf setting of "printing = cups" + - * another Samba-smb.conf setting of "printcap = cups" + + another Samba-smb.conf setting of "printcap = cups" + + + + Note, that in this case all other manually set printing-related commands (like "print command", "lpq command", "lprm command", "lppause command" or "lpresume command") are ignored and they should normally have no influence what-so-ever on your printing. + + If you want to do things manually, replace the "printing = cups" by "printing = bsd". Then your manually set commands may work (haven't tested this), and a "print command = lp -d %P %s; rm %s" may do what you need. + + You forgot to mention the CUPS version you're using. If you did set things up as described in the man pages, then the Samba spool files should be deleted. Otherwise it may be a bug. On the CUPS side, you can control the behaviour as described above. + + + If you have more problems, post the output of these commands: + + + grep -v ^# /etc/cups/cupsd.conf | grep -v ^$ grep -v ^# /etc/samba/smb.conf | grep -v ^$ | grep -v "^;" + + + (adapt paths as needed). These commands sanitize the files and cut out the empty lines and lines with comments, providing the "naked settings" in a compact way. + diff --git a/docs/docbook/projdoc/ServerType.sgml b/docs/docbook/projdoc/ServerType.sgml index 65544572b7..41b1c0ed2f 100644 --- a/docs/docbook/projdoc/ServerType.sgml +++ b/docs/docbook/projdoc/ServerType.sgml @@ -21,6 +21,7 @@ different type of servers: Primary Domain Controller Backup Domain Controller + ADS Domain Controller diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml index d06d86337d..1a2e285596 100644 --- a/docs/docbook/projdoc/samba-doc.sgml +++ b/docs/docbook/projdoc/samba-doc.sgml @@ -26,6 +26,7 @@ + ]> @@ -112,6 +113,7 @@ part each cover one specific feature. &Samba-PAM; &MS-Dfs-Setup; &PRINTER-DRIVER2; +&CUPS; &WINBIND; &BROWSING; &VFS; -- cgit