ading new files from 3.0

(This used to be commit 99feae7b5b1c229a925367b87c0c0f636d9a2d75)

diff --git a/docs/docbook/devdoc/.cvsignore b/docs/docbook/devdoc/.cvsignore
new file mode 100644 (file)
index 0000000..3bbac30
--- /dev/null
+++ b/docs/docbook/devdoc/.cvsignore
@@ -0,0 +1 @@
+attributions.xml

diff --git a/docs/docbook/devdoc/vfs.xml b/docs/docbook/devdoc/vfs.xml
new file mode 100644 (file)
index 0000000..ed2afef
--- /dev/null
+++ b/docs/docbook/devdoc/vfs.xml
@@ -0,0 +1,797 @@
+<chapter id="vfs">
+<chapterinfo>
+       <author>
+               <firstname>Alexander</firstname><surname>Bokovoy</surname>
+               <affiliation>
+                       <address><email>ab@samba.org</email></address>
+               </affiliation>
+       </author>
+       <author>
+               <firstname>Stefan</firstname><surname>Metzmacher</surname>
+               <affiliation>
+                       <address><email>metze@metzemix.de</email></address>
+               </affiliation>
+       </author>
+       <pubdate> 27 May 2003 </pubdate>
+</chapterinfo>
+
+<title>VFS Modules</title>
+
+<sect1>
+<title>The Samba (Posix) VFS layer</title>
+
+<sect2>
+<title>The general interface</title>
+
+<para>
+Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the
+struct vfs_ops and tree macros to make it easier to call the operations.
+(Take a look at <filename>include/vfs.h</filename> and <filename>include/vfs_macros.h</filename>.)
+</para>
+
+<para><programlisting>
+typedef enum _vfs_op_type {
+       SMB_VFS_OP_NOOP = -1,
+
+       ...
+
+       /* File operations */
+
+       SMB_VFS_OP_OPEN,
+       SMB_VFS_OP_CLOSE,
+       SMB_VFS_OP_READ,
+       SMB_VFS_OP_WRITE,
+       SMB_VFS_OP_LSEEK,
+       SMB_VFS_OP_SENDFILE,
+
+       ...
+
+       SMB_VFS_OP_LAST
+} vfs_op_type;
+</programlisting></para>
+
+<para>This struct contains the function and handle pointers for all operations.<programlisting>
+struct vfs_ops {
+       struct vfs_fn_pointers {
+               ...
+               
+               /* File operations */
+               
+               int (*open)(struct vfs_handle_struct *handle,
+                       struct connection_struct *conn,
+                       const char *fname, int flags, mode_t mode);
+               int (*close)(struct vfs_handle_struct *handle,
+                       struct files_struct *fsp, int fd);
+               ssize_t (*read)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, void *data, size_t n);
+               ssize_t (*write)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, 
+                       const void *data, size_t n);
+               SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, 
+                       SMB_OFF_T offset, int whence);
+               ssize_t (*sendfile)(struct vfs_handle_struct *handle, 
+                       int tofd, files_struct *fsp, int fromfd, 
+                       const DATA_BLOB *header, SMB_OFF_T offset, size_t count);
+
+               ...
+       } ops;
+       
+       struct vfs_handles_pointers {
+               ...
+               
+               /* File operations */
+               
+               struct vfs_handle_struct *open;
+               struct vfs_handle_struct *close;
+               struct vfs_handle_struct *read;
+               struct vfs_handle_struct *write;
+               struct vfs_handle_struct *lseek;
+               struct vfs_handle_struct *sendfile;
+               
+               ...
+       } handles;
+};
+</programlisting></para>
+
+<para>
+This macros SHOULD be used to call any vfs operation.
+DO NOT ACCESS conn-&gt;vfs.ops.* directly !!!
+<programlisting>
+...
+       
+/* File operations */
+#define SMB_VFS_OPEN(conn, fname, flags, mode) \
+       ((conn)-&gt;vfs.ops.open((conn)-&gt;vfs.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_CLOSE(fsp, fd) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.close(\
+       (fsp)-&gt;conn-&gt;vfs.handles.close, (fsp), (fd)))
+#define SMB_VFS_READ(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.read(\
+       (fsp)-&gt;conn-&gt;vfs.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_WRITE(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.write(\
+       (fsp)-&gt;conn-&gt;vfs.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.lseek(\
+       (fsp)-&gt;conn-&gt;vfs.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.sendfile(\
+       (fsp)-&gt;conn-&gt;vfs.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+
+...
+</programlisting></para>
+
+</sect2>
+
+<sect2>
+<title>Possible VFS operation layers</title>
+
+<para>
+These values are used by the VFS subsystem when building the conn-&gt;vfs 
+and conn-&gt;vfs_opaque structs for a connection with multiple VFS modules. 
+Internally, Samba differentiates only opaque and transparent layers at this process.
+Other types are used for providing better diagnosing facilities.
+</para>
+
+<para>
+Most modules will provide transparent layers. Opaque layer is for modules
+which implement actual file system calls (like DB-based VFS). For example,
+default POSIX VFS which is built in into Samba is an opaque VFS module.
+</para>
+
+<para>    
+Other layer types (logger, splitter, scanner) were designed to provide different 
+degree of transparency and for diagnosing VFS module behaviour.
+</para>
+
+<para>
+Each module can implement several layers at the same time provided that only
+one layer is used per each operation.
+</para>
+
+<para><programlisting>
+typedef enum _vfs_op_layer {
+       SMB_VFS_LAYER_NOOP = -1,        /* - For using in VFS module to indicate end of array */
+                                       /*   of operations description */
+       SMB_VFS_LAYER_OPAQUE = 0,       /* - Final level, does not call anything beyond itself */
+       SMB_VFS_LAYER_TRANSPARENT,      /* - Normal operation, calls underlying layer after */
+                                       /*   possibly changing passed data */
+       SMB_VFS_LAYER_LOGGER,           /* - Logs data, calls underlying layer, logging may not */
+                                       /*   use Samba VFS */
+       SMB_VFS_LAYER_SPLITTER,         /* - Splits operation, calls underlying layer _and_ own facility, */
+                                       /*   then combines result */
+       SMB_VFS_LAYER_SCANNER           /* - Checks data and possibly initiates additional */
+                                       /*   file activity like logging to files _inside_ samba VFS */
+} vfs_op_layer;
+</programlisting></para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>The Interaction between the Samba VFS subsystem and the modules</title>
+
+<sect2>
+<title>Initialization and registration</title>
+
+<para>
+As each Samba module a VFS module should have a 
+<programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or
+<programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module.
+</para>
+
+<para>
+This should be the only non static function inside the module.
+Global variables should also be static!
+</para>
+
+<para>
+The module should register its functions via the
+<programlisting>
+NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
+</programlisting> function.
+</para>
+
+<variablelist>
+
+<varlistentry><term>version</term>
+<listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
+</varlistentry>
+
+<varlistentry><term>name</term>
+<listitem><para>this is the name witch can be listed in the 
+<command>vfs objects</command> parameter to use this module.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>vfs_op_tuples</term>
+<listitem><para>
+this is an array of vfs_op_tuple's.
+(vfs_op_tuples is descripted in details below.)
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+For each operation the module wants to provide it has a entry in the 
+vfs_op_tuple array.
+</para>
+
+<programlisting>
+typedef struct _vfs_op_tuple {
+       void* op;
+       vfs_op_type type;
+       vfs_op_layer layer;
+} vfs_op_tuple;
+</programlisting>
+
+<variablelist>
+
+<varlistentry><term>op</term>
+<listitem><para>the function pointer to the specified function.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>type</term>
+<listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>layer</term>
+<listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>A simple example:</para>
+
+<programlisting>
+static vfs_op_tuple example_op_tuples[] = {    
+       {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
+
+       {SMB_VFS_OP(example_rename),    SMB_VFS_OP_RENAME,      SMB_VFS_LAYER_OPAQUE},
+
+       /* This indicates the end of the array */
+       {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
+};
+
+NTSTATUS init_module(void)
+{
+       return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, &quot;example&quot;, example_op_tuples);
+}
+</programlisting>
+
+</sect2>
+
+<sect2>
+<title>How the Modules handle per connection data</title>
+
+<para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
+</para>
+
+<programlisting>
+typedef struct vfs_handle_struct {
+       struct vfs_handle_struct  *next, *prev;
+       const char *param;
+       struct vfs_ops vfs_next;
+       struct connection_struct *conn;
+       void *data;
+       void (*free_data)(void **data);
+} vfs_handle_struct;
+</programlisting>
+
+<variablelist>
+
+<varlistentry><term>param</term>
+<listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para>
+<para>e.g. for 'vfs objects = example:test' param would be &quot;test&quot;.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>vfs_next</term>
+<listitem><para>This vfs_ops struct contains the information for calling the next module operations.
+Use the SMB_VFS_NEXT_* macros to call a next module operations and
+don't access handle-&gt;vfs_next.ops.* directly!</para></listitem>
+</varlistentry>
+
+<varlistentry><term>conn</term>
+<listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>data</term>
+<listitem><para>This is a pointer for holding module private data.
+You can alloc data with connection life time on the handle-&gt;conn-&gt;mem_ctx TALLOC_CTX.
+But you can also manage the memory allocation yourself.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>free_data</term>
+<listitem><para>This is a function pointer to a function that free's the module private data.
+If you talloc your private data on the TALLOC_CTX handle-&gt;conn-&gt;mem_ctx,
+you can set this function pointer to NULL.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>Some useful MACROS for handle private data.
+</para>
+
+<programlisting>
+#define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
+       if (!(handle)||((datap=(type *)(handle)-&gt;data)==NULL)) { \
+               DEBUG(0,(&quot;%s() failed to get vfs_handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
+               ret; \
+       } \
+}
+
+#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
+       if (!(handle)) { \
+               DEBUG(0,(&quot;%s() failed to set handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
+               ret; \
+       } else { \
+               if ((handle)-&gt;free_data) { \
+                       (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
+               } \
+               (handle)-&gt;data = (void *)datap; \
+               (handle)-&gt;free_data = free_fn; \
+       } \
+}
+
+#define SMB_VFS_HANDLE_FREE_DATA(handle) { \
+       if ((handle) &amp;&amp; (handle)-&gt;free_data) { \
+               (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
+       } \
+}
+</programlisting>
+
+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
+
+<para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
+</para>
+
+<programlisting>
+...
+/* File operations */
+#define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
+       ((conn)-&gt;vfs_opaque.ops.open(\
+       (conn)-&gt;vfs_opaque.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.close(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.close,\
+        (fsp), (fd)))
+#define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.read(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.write(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.lseek(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.sendfile(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+...
+</programlisting>
+
+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
+
+<para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
+</para>
+
+<programlisting>
+...
+/* File operations */
+#define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
+       ((handle)-&gt;vfs_next.ops.open(\
+       (handle)-&gt;vfs_next.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
+       ((handle)-&gt;vfs_next.ops.close(\
+       (handle)-&gt;vfs_next.handles.close,\
+        (fsp), (fd)))
+#define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
+       ((handle)-&gt;vfs_next.ops.read(\
+       (handle)-&gt;vfs_next.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
+       ((handle)-&gt;vfs_next.ops.write(\
+       (handle)-&gt;vfs_next.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
+       ((handle)-&gt;vfs_next.ops.lseek(\
+       (handle)-&gt;vfs_next.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
+       ((handle)-&gt;vfs_next.ops.sendfile(\
+       (handle)-&gt;vfs_next.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+...
+</programlisting>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Upgrading to the New VFS Interface</title>
+
+<sect2>
+<title>Upgrading from 2.2.* and 3.0aplha modules</title>
+
+<orderedlist>
+<listitem><para>
+Add &quot;vfs_handle_struct *handle, &quot; as first parameter to all vfs operation functions.
+e.g. example_connect(connection_struct *conn, const char *service, const char *user);
+-&gt;   example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
+</para></listitem>
+
+<listitem><para>
+Replace &quot;default_vfs_ops.&quot; with &quot;smb_vfs_next_&quot;.
+e.g. default_vfs_ops.connect(conn, service, user);
+-&gt;   smb_vfs_next_connect(conn, service, user);
+</para></listitem>
+
+<listitem><para>
+Uppercase all &quot;smb_vfs_next_*&quot; functions.
+e.g. smb_vfs_next_connect(conn, service, user);
+-&gt;   SMB_VFS_NEXT_CONNECT(conn, service, user);
+</para></listitem>
+
+<listitem><para>
+Add &quot;handle, &quot; as first parameter to all SMB_VFS_NEXT_*() calls.
+e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
+-&gt;   SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
+</para></listitem>
+
+<listitem><para>
+(Only for 2.2.* modules) 
+Convert the old struct vfs_ops example_ops to 
+a vfs_op_tuple example_op_tuples[] array.
+e.g.
+<programlisting>
+struct vfs_ops example_ops = {
+       /* Disk operations */
+       example_connect,                /* connect */
+       example_disconnect,             /* disconnect */
+       NULL,                           /* disk free *
+       /* Directory operations */
+       NULL,                           /* opendir */
+       NULL,                           /* readdir */
+       NULL,                           /* mkdir */
+       NULL,                           /* rmdir */
+       NULL,                           /* closedir */
+       /* File operations */
+       NULL,                           /* open */
+       NULL,                           /* close */
+       NULL,                           /* read  */
+       NULL,                           /* write */
+       NULL,                           /* lseek */
+       NULL,                           /* sendfile */
+       NULL,                           /* rename */
+       NULL,                           /* fsync */
+       example_stat,                   /* stat  */
+       example_fstat,                  /* fstat */
+       example_lstat,                  /* lstat */
+       NULL,                           /* unlink */
+       NULL,                           /* chmod */
+       NULL,                           /* fchmod */
+       NULL,                           /* chown */
+       NULL,                           /* fchown */
+       NULL,                           /* chdir */
+       NULL,                           /* getwd */
+       NULL,                           /* utime */
+       NULL,                           /* ftruncate */
+       NULL,                           /* lock */
+       NULL,                           /* symlink */
+       NULL,                           /* readlink */
+       NULL,                           /* link */
+       NULL,                           /* mknod */
+       NULL,                           /* realpath */
+       NULL,                           /* fget_nt_acl */
+       NULL,                           /* get_nt_acl */
+       NULL,                           /* fset_nt_acl */
+       NULL,                           /* set_nt_acl */
+
+       NULL,                           /* chmod_acl */
+       NULL,                           /* fchmod_acl */
+
+       NULL,                           /* sys_acl_get_entry */
+       NULL,                           /* sys_acl_get_tag_type */
+       NULL,                           /* sys_acl_get_permset */
+       NULL,                           /* sys_acl_get_qualifier */
+       NULL,                           /* sys_acl_get_file */
+       NULL,                           /* sys_acl_get_fd */
+       NULL,                           /* sys_acl_clear_perms */
+       NULL,                           /* sys_acl_add_perm */
+       NULL,                           /* sys_acl_to_text */
+       NULL,                           /* sys_acl_init */
+       NULL,                           /* sys_acl_create_entry */
+       NULL,                           /* sys_acl_set_tag_type */
+       NULL,                           /* sys_acl_set_qualifier */
+       NULL,                           /* sys_acl_set_permset */
+       NULL,                           /* sys_acl_valid */
+       NULL,                           /* sys_acl_set_file */
+       NULL,                           /* sys_acl_set_fd */
+       NULL,                           /* sys_acl_delete_def_file */
+       NULL,                           /* sys_acl_get_perm */
+       NULL,                           /* sys_acl_free_text */
+       NULL,                           /* sys_acl_free_acl */
+       NULL                            /* sys_acl_free_qualifier */
+};
+</programlisting>
+-&gt;
+<programlisting> 
+static vfs_op_tuple example_op_tuples[] = {
+       {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
+       
+       {SMB_VFS_OP(example_fstat),     SMB_VFS_OP_FSTAT,       SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_stat),              SMB_VFS_OP_STAT,        SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_lstat),     SMB_VFS_OP_LSTAT,       SMB_VFS_LAYER_TRANSPARENT},
+
+       {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
+};
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+Move the example_op_tuples[] array to the end of the file. 
+</para></listitem>
+
+<listitem><para>
+Add the init_module() function at the end of the file.
+e.g.
+<programlisting>
+NTSTATUS init_module(void)
+{
+       return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,&quot;example&quot;,example_op_tuples);
+}
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+Check if your vfs_init() function does more then just prepare the vfs_ops structs or
+remember the struct smb_vfs_handle_struct.
+<simplelist>
+<member>If NOT you can remove the vfs_init() function.</member>
+<member>If YES decide if you want to move the code to the example_connect() operation or to the init_module(). And then remove vfs_init().
+  e.g. a debug class registration should go into init_module() and the allocation of private data should go to example_connect().</member>
+</simplelist>
+</para></listitem>
+
+<listitem><para>
+(Only for 3.0alpha* modules) 
+Check if your vfs_done() function contains needed code.
+<simplelist>
+<member>If NOT you can remove the vfs_done() function.</member>
+<member>If YES decide if you can move the code to the example_disconnect() operation. Otherwise register a SMB_EXIT_EVENT with smb_register_exit_event(); (Described in the <link linkend="modules">modules section</link>) And then remove vfs_done(). e.g. the freeing of private data should go to example_disconnect().
+</member>
+</simplelist>
+</para></listitem>
+
+<listitem><para>
+Check if you have any global variables left.
+Decide if it wouldn't be better to have this data on a connection basis.
+<simplelist>
+  <member>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</member>
+  <member>If YES pack all this data into a struct. You can use handle-&gt;data to point to such a struct on a per connection basis.</member>
+</simplelist>
+
+  e.g. if you have such a struct:
+<programlisting>    
+struct example_privates {
+       char *some_string;
+       int db_connection;
+};
+</programlisting>      
+first way of doing it:
+<programlisting>
+static int example_connect(vfs_handle_struct *handle,
+       connection_struct *conn, const char *service, 
+       const char* user)
+{
+       struct example_privates *data = NULL;
+
+       /* alloc our private data */
+       data = (struct example_privates *)talloc_zero(conn-&gt;mem_ctx, sizeof(struct example_privates));
+       if (!data) {
+               DEBUG(0,(&quot;talloc_zero() failed\n&quot;));
+               return -1;
+       }
+
+       /* init out private data */
+       data-&gt;some_string = talloc_strdup(conn-&gt;mem_ctx,&quot;test&quot;);
+       if (!data-&gt;some_string) {
+               DEBUG(0,(&quot;talloc_strdup() failed\n&quot;));
+               return -1;
+       }
+
+       data-&gt;db_connection = open_db_conn();
+
+       /* and now store the private data pointer in handle-&gt;data
+        * we don't need to specify a free_function here because
+        * we use the connection TALLOC context.
+        * (return -1 if something failed.)
+        */
+       VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
+
+       return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
+}
+
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       struct example_privates *data = NULL;
+       
+       /* get the pointer to our private data
+        * return -1 if something failed
+        */
+       SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
+       
+       /* do something here...*/
+       DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
+       
+       return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+second way of doing it:
+<programlisting>
+static void free_example_privates(void **datap)
+{
+       struct example_privates *data = (struct example_privates *)*datap;
+       
+       SAFE_FREE(data-&gt;some_string);
+       SAFE_FREE(data);
+       
+       *datap = NULL;
+       
+       return;
+}
+
+static int example_connect(vfs_handle_struct *handle, 
+       connection_struct *conn, const char *service, 
+       const char* user)
+{
+       struct example_privates *data = NULL;
+
+       /* alloc our private data */
+       data = (struct example_privates *)malloc(sizeof(struct example_privates));
+       if (!data) {
+               DEBUG(0,(&quot;malloc() failed\n&quot;));
+               return -1;
+       }
+
+       /* init out private data */
+       data-&gt;some_string = strdup(&quot;test&quot;);
+       if (!data-&gt;some_string) {
+               DEBUG(0,(&quot;strdup() failed\n&quot;));
+               return -1;
+       }
+
+       data-&gt;db_connection = open_db_conn();
+
+       /* and now store the private data pointer in handle-&gt;data
+        * we need to specify a free_function because we used malloc() and strdup().
+        * (return -1 if something failed.)
+        */
+       SMB_VFS_HANDLE_SET_DATA(handle, data, free_example_privates, struct example_privates, return -1);
+
+       return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
+}
+
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       struct example_privates *data = NULL;
+       
+       /* get the pointer to our private data
+        * return -1 if something failed
+        */
+       SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
+       
+       /* do something here...*/
+       DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
+       
+       return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+To make it easy to build 3rd party modules it would be usefull to provide
+configure.in, (configure), install.sh and Makefile.in with the module.
+(Take a look at the example in <filename>examples/VFS</filename>.)
+</para>
+
+<para>
+The configure script accepts <option>--with-samba-source</option> to specify 
+the path to the samba source tree.
+It also accept <option>--enable-developer</option> which lets the compiler 
+give you more warnings.  
+</para>
+
+<para>
+The idea is that you can extend this 
+<filename>configure.in</filename> and <filename>Makefile.in</filename> scripts
+for your module.
+</para></listitem>
+
+<listitem><para>
+Compiling &amp; Testing...
+<simplelist>
+<member><userinput>./configure <option>--enable-developer</option></userinput> ...</member>
+<member><userinput>make</userinput></member>
+<member>Try to fix all compiler warnings</member>
+<member><userinput>make</userinput></member>
+<member>Testing, Testing, Testing ...</member>
+</simplelist>
+</para></listitem>
+</orderedlist>
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Some Notes</title>
+
+<sect2>
+<title>Implement TRANSPARENT functions</title>
+
+<para>
+Avoid writing functions like this:
+
+<programlisting>
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+
+Overload only the functions you really need to!
+</para>
+
+</sect2>
+
+<sect2>
+<title>Implement OPAQUE functions</title>
+
+<para>
+If you want to just implement a better version of a 
+default samba opaque function
+(e.g. like a disk_free() function for a special filesystem) 
+it's ok to just overload that specific function.
+</para>
+
+<para>
+If you want to implement a database filesystem or
+something different from a posix filesystem.
+Make sure that you overload every vfs operation!!!
+</para>
+<para>
+Functions your FS does not support should be overloaded by something like this:
+e.g. for a readonly filesystem.
+</para>
+
+<programlisting>
+static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
+                       char *oldname, char *newname)
+{
+       DEBUG(10,(&quot;function rename() not allowed on vfs 'example'\n&quot;));
+       errno = ENOSYS;
+       return -1;
+}
+</programlisting>
+
+</sect2>
+
+</sect1>
+
+</chapter>

diff --git a/docs/docbook/devdoc/windows-debug.xml b/docs/docbook/devdoc/windows-debug.xml
new file mode 100644 (file)
index 0000000..3535c38
--- /dev/null
+++ b/docs/docbook/devdoc/windows-debug.xml
@@ -0,0 +1,19 @@
+<chapter id="windows-debug">
+       <chapterinfo>
+               &author.jelmer;
+               &author.tridge;
+       </chapterinfo>
+
+       <title>Finding useful information on windows</title>
+
+       <sect1><title>Netlogon debugging output</title>
+
+       <procedure>
+               <step><para>stop netlogon service on PDC</para></step>
+               <step><para>rename original netlogon.dll to netlogon.dll.original</para></step>
+               <step><para>copy checked version of netlogon.dll to system32 directory</para></step>
+               <step><para>set HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters\DBFlag to 0x20000004</para></step>
+               <step><para>start netlogon service on PDC</para></step>
+       </procedure>
+</sect1>
+</chapter>

diff --git a/docs/docbook/manpages/profiles.1.sgml b/docs/docbook/manpages/profiles.1.sgml
new file mode 100644 (file)
index 0000000..6fd2b6f
--- /dev/null
+++ b/docs/docbook/manpages/profiles.1.sgml
@@ -0,0 +1,86 @@
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+<!ENTITY % globalentities SYSTEM '../global.ent'> %globalentities;
+]>
+<refentry id="profiles.1">
+
+<refmeta>
+       <refentrytitle>profiles</refentrytitle>
+       <manvolnum>1</manvolnum>
+</refmeta>
+
+
+<refnamediv>
+       <refname>profiles</refname>
+       <refpurpose>A utility to report and change SIDs in registry files
+       </refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+       <cmdsynopsis>
+               <command>profiles</command>
+               <arg choice="opt">-v</arg>
+               <arg choice="opt">-c SID</arg>
+               <arg choice="opt">-n SID</arg>
+               <arg choice="req">file</arg>
+       </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+       <title>DESCRIPTION</title>
+
+       <para>This tool is part of the <citerefentry><refentrytitle>Samba</refentrytitle>
+       <manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+       <para><command>profiles</command> is a utility that 
+       reports and changes SIDs in windows registry files. It currently only 
+       supports NT.
+       </para>
+</refsect1>
+
+
+<refsect1>
+       <title>OPTIONS</title>
+
+       <variablelist>
+               <varlistentry>
+               <term>file</term>
+               <listitem><para>Registry file to view or edit.  </para></listitem>
+               </varlistentry>
+
+
+               <varlistentry>
+               <term>-v,--verbose</term>
+               <listitem><para>Increases verbosity of messages. 
+               </para></listitem>
+               </varlistentry>
+
+               <varlistentry>
+               <term>-c SID1 -n SID2</term>
+               <listitem><para>Change all occurences of SID1 in <filename>file</filename> by SID2.
+               </para></listitem>
+               </varlistentry>
+
+               &stdarg.help;
+               
+       </variablelist>
+</refsect1>
+
+<refsect1>
+       <title>VERSION</title>
+
+       <para>This man page is correct for version 3.0 of the Samba 
+       suite.</para>
+</refsect1>
+
+<refsect1>
+       <title>AUTHOR</title>
+       
+       <para>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.</para>
+       
+       <para>The profiles man page was written by Jelmer Vernooij. </para>
+</refsect1>
+
+</refentry>

diff --git a/docs/docbook/projdoc/.cvsignore b/docs/docbook/projdoc/.cvsignore
new file mode 100644 (file)
index 0000000..3bbac30
--- /dev/null
+++ b/docs/docbook/projdoc/.cvsignore
@@ -0,0 +1 @@
+attributions.xml

diff --git a/docs/docbook/projdoc/Backup.xml b/docs/docbook/projdoc/Backup.xml
new file mode 100644 (file)
index 0000000..b3c37ab
--- /dev/null
+++ b/docs/docbook/projdoc/Backup.xml
@@ -0,0 +1,36 @@
+<chapter id="Backup">
+<chapterinfo>
+       &author.jht;
+</chapterinfo>
+
+<title>Samba Backup Techniques</title>
+
+<sect1>
+<title>Note</title>
+
+<para>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+If you have something to contribute for this section please email it to
+<link url="mail://jht@samba.org">jht@samba.org</link>/
+</para>
+
+</sect1>
+
+<sect1>
+<title>Features and Benefits</title>
+
+<para>
+We need feedback from people who are backing up samba servers.
+We would like to know what software tools you are using to backup
+your samba server/s.
+</para>
+
+<para>
+In particular, if you have any success and / or failure stories you could
+share with other users this would be appreciated.
+</para>
+
+</sect1>
+
+</chapter>

diff --git a/docs/docbook/projdoc/DNS-DHCP-Configuration.xml b/docs/docbook/projdoc/DNS-DHCP-Configuration.xml
new file mode 100644 (file)
index 0000000..21bda63
--- /dev/null
+++ b/docs/docbook/projdoc/DNS-DHCP-Configuration.xml
@@ -0,0 +1,17 @@
+<chapter id="DNSDHCP">
+<chapterinfo>
+       &author.jht;
+</chapterinfo>
+
+<title>DNS and DHCP Configuration Guide</title>
+
+<sect1>
+<title>Note</title>
+
+<para>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+</para>
+
+</sect1>
+</chapter>

diff --git a/docs/docbook/projdoc/FastStart.xml b/docs/docbook/projdoc/FastStart.xml
new file mode 100644 (file)
index 0000000..a1aee9b
--- /dev/null
+++ b/docs/docbook/projdoc/FastStart.xml
@@ -0,0 +1,17 @@
+<chapter id="FastStart">
+<chapterinfo>
+       &author.jht;
+</chapterinfo>
+
+<title>Fast Start for the Impatient</title>
+
+<sect1>
+<title>Note</title>
+
+<para>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+</para>
+
+</sect1>
+</chapter>

diff --git a/docs/docbook/projdoc/HighAvailability.xml b/docs/docbook/projdoc/HighAvailability.xml
new file mode 100644 (file)
index 0000000..3cd7fac
--- /dev/null
+++ b/docs/docbook/projdoc/HighAvailability.xml
@@ -0,0 +1,17 @@
+<chapter id="SambaHA">
+<chapterinfo>
+       &author.jht;
+</chapterinfo>
+
+<title>High Availability Options</title>
+
+<sect1>
+<title>Note</title>
+
+<para>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+</para>
+
+</sect1>
+</chapter>

diff --git a/docs/docbook/projdoc/WindowsClientConfig.xml b/docs/docbook/projdoc/WindowsClientConfig.xml
new file mode 100644 (file)
index 0000000..ea1d4d5
--- /dev/null
+++ b/docs/docbook/projdoc/WindowsClientConfig.xml
@@ -0,0 +1,17 @@
+<chapter id="ClientConfig">
+<chapterinfo>
+       &author.jht;
+</chapterinfo>
+
+<title>MS Windows Network Configuration Guide</title>
+
+<sect1>
+<title>Note</title>
+
+<para>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+</para>
+
+</sect1>
+</chapter>

diff --git a/docs/docbook/smbdotconf/misc/valid.xml b/docs/docbook/smbdotconf/misc/valid.xml
new file mode 100644 (file)
index 0000000..b5756f0
--- /dev/null
+++ b/docs/docbook/smbdotconf/misc/valid.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="-valid"
+                context="S"
+                xmlns:samba="http://samba.org/common">
+ <listitem>
+       <para> This parameter indicates whether a share is 
+       valid and thus can be used. When this parameter is set to false, 
+       the share will be in no way visible nor accessible.
+       </para>
+
+       <para>
+       This option should not be 
+       used by regular users but might be of help to developers. 
+       Samba uses this option internally to mark shares as deleted.
+       </para>
+
+       <para>Default: <emphasis>True</emphasis></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/printing/totalprintjobs.xml b/docs/docbook/smbdotconf/printing/totalprintjobs.xml
new file mode 100644 (file)
index 0000000..ccdb137
--- /dev/null
+++ b/docs/docbook/smbdotconf/printing/totalprintjobs.xml
@@ -0,0 +1,22 @@
+<samba:parameter name="total print jobs"
+                 context="G"
+                 print="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para>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 <citerefentry><refentrytitle>smbd</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> 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 <link linkend="MAXPRINTJOBS">
+    <parameter moreinfo="none">max print jobs</parameter></link>.
+    </para>
+               
+    <para>Default: <command moreinfo="none">total print jobs = 0</command></para>
+
+    <para>Example: <command moreinfo="none">total print jobs = 5000</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/protocol/clientusespnego.xml b/docs/docbook/smbdotconf/protocol/clientusespnego.xml
new file mode 100644 (file)
index 0000000..df25fbf
--- /dev/null
+++ b/docs/docbook/smbdotconf/protocol/clientusespnego.xml
@@ -0,0 +1,13 @@
+<samba:parameter name="client use spnego"
+                 context="G"
+                 developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para> This variable controls controls whether samba clients will try 
+    to use Simple and Protected NEGOciation (as specified by rfc2478) with 
+    WindowsXP and Windows2000 servers to agree upon an authentication mechanism. 
+       </para>
+
+    <para>Default:  <emphasis>client use spnego = yes</emphasis></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/protocol/mapaclinherit.xml b/docs/docbook/smbdotconf/protocol/mapaclinherit.xml
new file mode 100644 (file)
index 0000000..5b8ed7f
--- /dev/null
+++ b/docs/docbook/smbdotconf/protocol/mapaclinherit.xml
@@ -0,0 +1,17 @@
+<samba:parameter name="map acl inherit"
+                 context="S"
+                 advanced="1" wizard="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para>This boolean parameter controls whether <citerefentry><refentrytitle>smbd</refentrytitle>                                       
+    <manvolnum>8</manvolnum></citerefentry> will attempt to map the 'inherit' and 'protected'
+    access control entry flags stored in Windows ACLs into an extended attribute
+    called user.SAMBA_PAI. This parameter only takes effect if Samba is being run
+    on a platform that supports extended attributes (Linux and IRIX so far) and
+    allows the Windows 2000 ACL editor to correctly use inheritance with the Samba
+    POSIX ACL mapping code.
+    </para>
+               
+    <para>Default: <command moreinfo="none">map acl inherit = no</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/protocol/profileacls.xml b/docs/docbook/smbdotconf/protocol/profileacls.xml
new file mode 100644 (file)
index 0000000..6f2b3ec
--- /dev/null
+++ b/docs/docbook/smbdotconf/protocol/profileacls.xml
@@ -0,0 +1,33 @@
+<samba:parameter name="profile acls"
+                 context="S"
+                 advanced="1" wizard="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para>This boolean parameter controls whether <citerefentry><refentrytitle>smbd</refentrytitle>                                       
+    <manvolnum>8</manvolnum></citerefentry> 
+       This boolean parameter was added to fix the problems that people have been
+       having with storing user profiles on Samba shares from Windows 2000 or
+       Windows XP clients. New versions of Windows 2000 or Windows XP service
+       packs do security ACL checking on the owner and ability to write of the
+       profile directory stored on a local workstation when copied from a Samba
+       share. When not in domain mode with winbindd then the security info copied
+       onto the local workstation has no meaning to the logged in user (SID) on
+       that workstation so the profile storing fails. Adding this parameter
+       onto a share used for profile storage changes two things about the
+       returned Windows ACL. Firstly it changes the owner and group owner
+       of all reported files and directories to be BUILTIN\\Administrators,
+       BUILTIN\\Users respectively (SIDs S-1-5-32-544, S-1-5-32-545). Secondly
+       it adds an ACE entry of "Full Control" to the SID BUILTIN\\Users to
+       every returned ACL. This will allow any Windows 2000 or XP workstation
+       user to access the profile. Note that if you have multiple users logging
+       on to a workstation then in order to prevent them from being able to access
+       each others profiles you must remove the "Bypass traverse checking" advanced
+       user right. This will prevent access to other users profile directories as
+       the top level profile directory (named after the user) is created by the
+       workstation profile code and has an ACL restricting entry to the directory
+       tree to the owning user.
+    </para>
+               
+    <para>Default: <command moreinfo="none">profile acls = no</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/security/clientlanmanauth.xml b/docs/docbook/smbdotconf/security/clientlanmanauth.xml
new file mode 100644 (file)
index 0000000..a427198
--- /dev/null
+++ b/docs/docbook/smbdotconf/security/clientlanmanauth.xml
@@ -0,0 +1,28 @@
+<samba:parameter name="client lanman auth"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para>This parameter determines whether or not <citerefentry><refentrytitle>smbclient</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> and other samba client
+    tools will attempt to authenticate itself to servers using the
+    weaker LANMAN password hash. If disabled, only server which support NT 
+    password hashes (e.g. Windows NT/2000, Samba, etc... but not 
+    Windows 95/98) will be able to be connected from the Samba client.</para>
+
+    <para>The LANMAN encrypted response is easily broken, due to it's
+    case-insensitive nature, and the choice of algorithm.  Clients
+    without Windows 95/98 servers are advised to disable
+    this option.  </para>
+
+    <para>Disabling this option will also disable the <command
+    moreinfo="none">client plaintext auth</command> option</para>
+
+    <para>Likewise, if the <command moreinfo="none">client ntlmv2
+    auth</command> parameter is enabled, then only NTLMv2 logins will be
+    attempted.  Not all servers support NTLMv2, and most will require
+    special configuration to us it.</para>
+
+    <para>Default : <command moreinfo="none">client lanman auth = yes</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/security/clientntlmv2auth.xml b/docs/docbook/smbdotconf/security/clientntlmv2auth.xml
new file mode 100644 (file)
index 0000000..0bf1964
--- /dev/null
+++ b/docs/docbook/smbdotconf/security/clientntlmv2auth.xml
@@ -0,0 +1,26 @@
+<samba:parameter name="client ntlmv2 auth"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+    <para>This parameter determines whether or not <citerefentry><refentrytitle>smbclient</refentrytitle>
+    <manvolnum>8</manvolnum></citerefentry> will attempt to
+    authenticate itself to servers using the NTLMv2 encrypted password
+    response.</para>
+
+    <para>If enabled, only an NTLMv2 and LMv2 response (both much more
+    secure than earlier versions) will be sent.  Many servers
+    (including NT4 &lt; SP4, Win9x and Samba 2.2) are not compatible with
+    NTLMv2.  </para>
+
+    <para>If disabled, an NTLM response (and possibly a LANMAN response)
+    will be sent by the client, depending on the value of <command
+    moreinfo="none">client lanman auth</command>.  </para>
+
+    <para>Note that some sites (particularly
+    those following 'best practice' security polices) only allow NTLMv2
+    responses, and not the weaker LM or NTLM.</para>
+
+       <para>Default : <command moreinfo="none">client ntlmv2 auth = no</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/vfs/vfsobjects.xml b/docs/docbook/smbdotconf/vfs/vfsobjects.xml
new file mode 100644 (file)
index 0000000..32a10b5
--- /dev/null
+++ b/docs/docbook/smbdotconf/vfs/vfsobjects.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="vfs objects"
+                 context="S"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>This parameter specifies the backend names which 
+       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. </para>
+               
+       <para>Default: <emphasis>no value</emphasis></para>
+
+       <para>Example: <command moreinfo="none">vfs objects = extd_audit recycle</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/enableridalgorithm.xml b/docs/docbook/smbdotconf/winbind/enableridalgorithm.xml
new file mode 100644 (file)
index 0000000..86786f0
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/enableridalgorithm.xml
@@ -0,0 +1,17 @@
+<samba:parameter name="enable rid algorithm"
+                 context="G"
+                 advanced="1" developer="1" hide="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>This option is used to control whether or not smbd in Samba 3.0 should fallback
+       to the algorithm used by Samba 2.2 to generate user and group RIDs.  The longterm
+       development goal is to remove the algorithmic mappings of RIDs altogether, but 
+       this has proved to be difficult.  This parameter is mainly provided so that
+       developers can turn the algorithm on and off and see what breaks.  This parameter
+       should not be disabled by non-developers because certain features in Samba will fail 
+       to work without it.
+       </para>
+
+       <para>Default: <command moreinfo="none">enable rid algorithm = &lt;yes&gt;</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/idmapgid.xml b/docs/docbook/smbdotconf/winbind/idmapgid.xml
new file mode 100644 (file)
index 0000000..8bd46a8
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/idmapgid.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="idmap gid"
+                 context="G"
+                 advanced="1" developer="1" hide="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+
+       <para>The idmap gid parameter specifies the range of group ids that are allocated for
+       the purpose of mapping UNX groups to NT group SIDs. This range of group ids should have no 
+       existing local or NIS groups within it as strange conflicts can occur otherwise.</para>
+
+       <para>The availability of an idmap gid range is essential for correct operation of
+       all group mapping.</para>
+
+       <para>Default: <command moreinfo="none">idmap gid = &lt;empty string&gt;</command></para>
+
+       <para>Example: <command moreinfo="none">idmap gid = 10000-20000</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/idmapuid.xml b/docs/docbook/smbdotconf/winbind/idmapuid.xml
new file mode 100644 (file)
index 0000000..5e6a245
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/idmapuid.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="idmap uid"
+                 context="G"
+                 advanced="1" developer="1" hide="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>The idmap uid parameter specifies the range of user ids that are allocated for use
+       in mapping UNIX users to NT user SIDs. This range of ids should have no existing local
+       or NIS users within it as strange conflicts can occur otherwise.</para>
+
+       <para>Default: <command moreinfo="none">idmap uid = &lt;empty string&gt;</command></para>
+               
+       <para>Example: <command moreinfo="none">idmap uid = 10000-20000</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/templateprimarygroup.xml b/docs/docbook/smbdotconf/winbind/templateprimarygroup.xml
new file mode 100644 (file)
index 0000000..bd59ea7
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/templateprimarygroup.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="template primary group"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>This option defines the default primary group for 
+       each user created by <citerefentry><refentrytitle>winbindd</refentrytitle>
+        <manvolnum>8</manvolnum></citerefentry>'s local account management
+       functions (similar to the 'add user script').
+       </para>
+
+       <para>Default: <command moreinfo="none">template primary group = nobody</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/winbindenablelocalaccounts.xml b/docs/docbook/smbdotconf/winbind/winbindenablelocalaccounts.xml
new file mode 100644 (file)
index 0000000..f6e7cfb
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/winbindenablelocalaccounts.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="winbind enable local accounts"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>This parameter controls whether or not winbindd 
+       will act as a stand in replacement for the various account
+       management hooks in smb.conf (e.g. 'add user script').
+       If enabled, winbindd will support the creation of local 
+       users and groups as another source of UNIX account information
+       available via getpwnam() or getgrgid(), etc...
+       </para>
+
+       <para>Default: <command moreinfo="none">winbind enable local accounts = yes</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/smbdotconf/winbind/winbindtrusteddomainsonly.xml b/docs/docbook/smbdotconf/winbind/winbindtrusteddomainsonly.xml
new file mode 100644 (file)
index 0000000..bf38313
--- /dev/null
+++ b/docs/docbook/smbdotconf/winbind/winbindtrusteddomainsonly.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="winbind trusted domains only"
+                 context="G"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://samba.org/common">
+<listitem>
+       <para>This parameter is designed to allow Samba servers that
+       are members of a Samba controlled domain to use UNIX accounts
+       distributed vi NIS, rsync, or LDAP as the uid's for winbindd users
+       in the hosts primary domain.  Therefore, the user 'SAMBA\user1' would
+       be mapped to the account 'user1' in /etc/passwd instead of allocating
+       a new uid for him or her.
+       </para>
+
+       <para>Default: <command moreinfo="none">winbind trusted domains only = &lt;no&gt;</command></para>
+</listitem>
+</samba:parameter>

diff --git a/docs/docbook/xslt/generate-attributions.xsl b/docs/docbook/xslt/generate-attributions.xsl
new file mode 100644 (file)
index 0000000..c781a77
--- /dev/null
+++ b/docs/docbook/xslt/generate-attributions.xsl
@@ -0,0 +1,67 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:exsl="http://exslt.org/common"
+                xmlns:samba="http://samba.org/common"
+                               version="1.1"
+                extension-element-prefixes="exsl">
+
+<xsl:output method="xml" omit-xml-declaration="yes"/>
+
+<!-- Remove all character data -->
+<xsl:template match="@*|node()">
+   <xsl:apply-templates select="@*|node()"/>
+</xsl:template>
+
+<xsl:template match="book">
+       <xsl:element name="variablelist">
+       <xsl:apply-templates/>
+       </xsl:element>
+</xsl:template>
+
+<xsl:template match="chapter">
+       <xsl:element name="varlistentry">
+               <xsl:element name="term">
+                       <xsl:element name="link">
+                               <xsl:attribute name="linkend"><xsl:value-of select="@id"/></xsl:attribute>
+                               <xsl:value-of select="title"/>
+                       </xsl:element>
+               </xsl:element>
+               <xsl:element name="listitem">
+                       <xsl:element name="para">
+                               <xsl:element name="itemizedlist">
+                               <xsl:apply-templates/>
+                               </xsl:element>
+                       </xsl:element>
+               </xsl:element>
+       </xsl:element>
+</xsl:template>
+
+<xsl:template match="author">
+       <xsl:element name="listitem">
+               <xsl:element name="para">
+                       <xsl:value-of select="firstname"/><xsl:text> </xsl:text><xsl:value-of select="surname"/>
+                       <xsl:choose>
+                               <xsl:when test="affiliation/address/email != ''">
+                                       <xsl:text> &lt;</xsl:text>
+                                       <xsl:element name="ulink">
+                                               <xsl:attribute name="url">
+                                                       <xsl:text>mailto:</xsl:text>
+                                                       <xsl:value-of select="affiliation/address/email"/>
+                                               </xsl:attribute>
+                                               <xsl:value-of select="affiliation/address/email"/>
+                                       </xsl:element>
+                                       <xsl:text>&gt;</xsl:text>
+                               </xsl:when>
+                       </xsl:choose>
+                       <xsl:choose>
+                               <xsl:when test="contrib != ''">
+                                       <xsl:text> (</xsl:text>
+                                               <xsl:value-of select="contrib"/>
+                                       <xsl:text>) </xsl:text>
+                                       </xsl:when>
+                       </xsl:choose>
+               </xsl:element>
+       </xsl:element>
+</xsl:template>
+
+</xsl:stylesheet>

diff --git a/docs/htmldocs/AccessControls.html b/docs/htmldocs/AccessControls.html
new file mode 100644 (file)
index 0000000..044d347
--- /dev/null
+++ b/docs/htmldocs/AccessControls.html
@@ -0,0 +1,660 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 13. File, Directory and Share Access Controls</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="groupmapping.html" title="Chapter 12. Mapping MS Windows and Unix Groups"><link rel="next" href="locking.html" title="Chapter 14. File and Record Locking"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 13. File, Directory and Share Access Controls</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="groupmapping.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="locking.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="AccessControls"></a>Chapter 13. File, Directory and Share Access Controls</h2></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jht@samba.org">jht@samba.org</a>&gt;</tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Jeremy</span> <span class="surname">Allison</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jra@samba.org">jra@samba.org</a>&gt;</tt></p></div></div></div></div><div><p class="pubdate">May 10, 2003</p></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="AccessControls.html#id2920271">Features and Benefits</a></dt><dt><a href="AccessControls.html#id2920308">File System Access Controls</a></dt><dd><dl><dt><a href="AccessControls.html#id2920326">MS Windows NTFS Comparison with Unix File Systems</a></dt><dt><a href="AccessControls.html#id2920583">Managing Directories</a></dt><dt><a href="AccessControls.html#id2920678">File and Directory Access Control</a></dt></dl></dd><dt><a href="AccessControls.html#id2920894">Share Definition Access Controls</a></dt><dd><dl><dt><a href="AccessControls.html#id2922074">User and Group Based Controls</a></dt><dt><a href="AccessControls.html#id2922346">File and Directory Permissions Based Controls</a></dt><dt><a href="AccessControls.html#id2922591">Miscellaneous Controls</a></dt></dl></dd><dt><a href="AccessControls.html#id2922807">Access Controls on Shares</a></dt><dd><dl><dt><a href="AccessControls.html#id2922879">Share Permissions Management</a></dt></dl></dd><dt><a href="AccessControls.html#id2923178">MS Windows Access Control Lists and Unix Interoperability</a></dt><dd><dl><dt><a href="AccessControls.html#id2923186">Managing UNIX permissions Using NT Security Dialogs</a></dt><dt><a href="AccessControls.html#id2923224">Viewing File Security on a Samba Share</a></dt><dt><a href="AccessControls.html#id2923303">Viewing file ownership</a></dt><dt><a href="AccessControls.html#id2923425">Viewing File or Directory Permissions</a></dt><dt><a href="AccessControls.html#id2923653">Modifying file or directory permissions</a></dt><dt><a href="AccessControls.html#id2923805">Interaction with the standard Samba create mask 
+               parameters</a></dt><dt><a href="AccessControls.html#id2924134">Interaction with the standard Samba file attribute 
+               mapping</a></dt></dl></dd><dt><a href="AccessControls.html#id2924210">Common Errors</a></dt><dd><dl><dt><a href="AccessControls.html#id2924224">Users can not write to a public share</a></dt><dt><a href="AccessControls.html#id2924604">I have set force user and Samba still makes root the owner of all the files
+                       I touch!</a></dt></dl></dd></dl></div><p>
+Advanced MS Windows users are frequently perplexed when file, directory and share manipulation of
+resources shared via Samba do not behave in the manner they might expect. MS Windows network
+administrators are often confused regarding network access controls and what is the best way to
+provide users with the type of access they need while protecting resources from the consequences
+of untoward access capabilities.
+</p><p>
+Unix administrators frequently are not familiar with the MS Windows environment and in particular
+have difficulty in visualizing what the MS Windows user wishes to achieve in attempts to set file
+and directory access permissions. 
+</p><p>
+The problem lies in the differences in how file and directory permissions and controls work
+between the two environments. This difference is one that Samba can not completely hide, even
+though it does try to make the chasm transparent.
+</p><p>
+POSIX Access Control List technology has been available (along with Extended Attributes)
+for Unix for many years, yet there is little evidence today of any significant use. This
+explains to some extent the slow adoption of ACLs into commercial Linux products. MS Windows
+administrators are astounded at this given that ACLs were a foundational capability of the now
+decade old MS Windows NT operating system.
+</p><p>
+The purpose of this chapter is to present each of the points of control that are possible with
+Samba-3 in the hope that this will help the network administrator to find the optimum method
+for delivering the best environment for MS Windows desktop users.
+</p><p>
+This is an opportune point to mention that it should be borne in mind that Samba was created to
+provide a means of interoperability and interchange of data between two operating environments
+that are quite different. It was never the intent to make Unix/Linux like MS Windows NT. Instead
+the purpose was an is to provide a sufficient level of exchange of data between the two environments.
+What is available today extends well beyond early plans and expectations, yet the gap continues to
+shrink.
+</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2920271"></a>Features and Benefits</h2></div></div><div></div></div><p>
+       Samba offers a lot of flexibility in file system access management. These are the key access control
+       facilities present in Samba today:
+       </p><div class="itemizedlist"><p class="title"><b>Samba Access Control Facilities</b></p><ul type="disc"><li><p>
+               <span class="emphasis"><em>Unix File and Directory Permissions</em></span>
+               </p><p>
+                       Samba honours and implements Unix file system access controls. Users
+                       who access a Samba server will do so as a particular MS Windows user.
+                       This information is passed to the Samba server as part of the logon or
+                       connection setup process. Samba uses this user identity to validate
+                       whether or not the user should be given access to file system resources
+                       (files and directories). This chapter provides an overview for those
+                       to whom the Unix permissions and controls are a little strange or unknown.
+                       </p></li><li><p>
+               <span class="emphasis"><em>Samba Share Definitions</em></span>
+               </p><p>
+                       In configuring share settings and controls in the <tt class="filename">smb.conf</tt> file
+                       the network administrator can exercise over-rides to native file
+                       system permissions and behaviours. This can be handy and convenient
+                       to affect behaviour that is more like what MS Windows NT users expect
+                       but it is seldom the <span class="emphasis"><em>best</em></span> way to achieve this.
+                       The basic options and techniques are described herein.
+                       </p></li><li><p>
+               <span class="emphasis"><em>Samba Share ACLs</em></span>
+               </p><p>
+                       Just like it is possible in MS Windows NT to set ACLs on shares
+                       themselves, so it is possible to do this in Samba.
+                       Very few people make use of this facility, yet it remains on of the
+                       easiest ways to affect access controls (restrictions) and can often
+                       do so with minimum invasiveness compared with other methods.
+                       </p></li><li><p>
+               <span class="emphasis"><em>MS Windows ACLs through Unix POSIX ACLs</em></span>
+               </p><p>
+                       The use of POSIX ACLs on Unix/Linux is possible ONLY if the underlying
+                       operating system supports them. If not, then this option will not be
+                       available to you. Current Unix technology platforms have native support
+                       for POSIX ACLs. There are patches for the Linux kernel that provide
+                       this also. Sadly, few Linux platforms ship today with native ACLs and
+                       Extended Attributes enabled. This chapter has pertinent information
+                       for users of platforms that support them.
+                       </p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2920308"></a>File System Access Controls</h2></div></div><div></div></div><p>
+Perhaps the most important recognition to be made is the simple fact that MS Windows NT4 / 200x / XP
+implement a totally divergent file system technology from what is provided in the Unix operating system
+environment. Firstly we should consider what the most significant differences are, then we shall look
+at how Samba helps to bridge the differences.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2920326"></a>MS Windows NTFS Comparison with Unix File Systems</h3></div></div><div></div></div><p>
+       Samba operates on top of the Unix file system. This means it is subject to Unix file system conventions
+       and permissions. It also means that if the MS Windows networking environment requires file system
+       behaviour that differs from unix file system behaviour then somehow Samba is responsible for emulating
+       that in a transparent and consistent manner.
+       </p><p>
+       It is good news that Samba does this to a very large extent and on top of that provides a high degree
+       of optional configuration to over-ride the default behaviour. We will look at some of these over-rides,
+       but for the greater part we will stay within the bounds of default behaviour. Those wishing to explore
+       to depths of control ability should review the <tt class="filename">smb.conf</tt> man page.
+       </p><div class="variablelist"><p class="title"><b>File System Feature Comparison</b></p><dl><dt><span class="term">Name Space</span></dt><dd><p>
+               MS Windows NT4 / 200x/ XP files names may be up to 254 characters long, Unix file names
+               may be 1023 characters long. In MS Windows file extensions indicate particular file types,
+               in Unix this is not so rigorously observed as all names are considered arbitrary. 
+               </p><p>
+               What MS Windows calls a Folder, Unix calls a directory,
+               </p></dd><dt><span class="term">Case Sensitivity</span></dt><dd><p>
+               MS Windows file names are generally Upper Case if made up of 8.3 (ie: 8 character file name
+               and 3 character extension. If longer than 8.3 file names are Case Preserving, and Case
+               Insensitive.
+               </p><p>
+               Unix file and directory names are Case Sensitive and Case Preserving. Samba implements the
+               MS Windows file name behaviour, but it does so as a user application. The Unix file system
+               provides no mechanism to perform case insensitive file name lookups. MS Windows does this
+               by default. This means that Samba has to carry the processing overhead to provide features
+               that are NOT native to the Unix operating system environment.
+               </p><p>
+               Consider the following, all are unique Unix names but one single MS Windows file name:
+               <tt class="computeroutput">
+                               MYFILE.TXT
+                               MyFile.txt
+                               myfile.txt
+               </tt>
+               So clearly, In an MS Windows file name space these three files CAN NOT co-exist! But in Unix 
+               they can. So what should Samba do if all three are present? Answer, the one that is lexically
+               first will be accessible to MS Windows users, the others are invisible and unaccessible - any
+               other solution would be suicidal.
+               </p></dd><dt><span class="term">Directory Separators</span></dt><dd><p>
+               MS Windows and DOS uses the back-slash '\' as a directory delimiter, Unix uses the forward-slash '/'
+               as it's directory delimiter. This is transparently handled by Samba.
+               </p></dd><dt><span class="term">Drive Identification</span></dt><dd><p>
+               MS Windows products support a notion of drive letters, like <b class="command">C:</b> to represent
+               disk partitions. Unix has NO concept if separate identifiers for file partitions since each
+               such file system is <tt class="filename">mounted</tt> to become part of the over-all directory tree.
+               The Unix directory tree begins at '/', just like the root of a DOS drive is specified like
+               <b class="command">C:\</b>.
+               </p></dd><dt><span class="term">File Naming Conventions</span></dt><dd><p>
+               MS Windows generally never experiences file names that begin with a '.', while in Unix these
+               are commonly found in a user's home directory. Files that begin with a '.' are typically
+               either start up files for various Unix applications, or they may be files that contain
+               start-up configuration data.
+               </p></dd><dt><span class="term">Links and Short-Cuts</span></dt><dd><p>
+               MS Windows make use of &quot;links and Short-Cuts&quot; that are actually special types of files that will
+               redirect an attempt to execute the file to the real location of the file. Unix knows of file and directory
+               links, but they are entirely different from what MS Windows users are used to.
+               </p><p>
+               Symbolic links are files in Unix that contain the actual location of the data (file OR directory). An
+               operation (like read or write) will operate directly on the file referenced. Symbolic links are also
+               referred to as 'soft links'. A hard link is something that MS Windows is NOT familiar with. It allows
+               one physical file to be known simultaneously by more than one file name.
+               </p></dd></dl></div><p>
+       There are many other subtle differences that may cause the MS Windows administrator some temporary discomfort
+       in the process of becoming familiar with Unix/Linux. These are best left for a text that is dedicated to the
+       purpose of Unix/Linux training/education.
+       </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2920583"></a>Managing Directories</h3></div></div><div></div></div><p>
+       There are three basic operations for managing directories, <b class="command">create, delete, rename</b>.
+       </p><div class="table"><a name="id2920603"></a><p class="title"><b>Table 13.1. Managing directories with unix and windows</b></p><table summary="Managing directories with unix and windows" border="1"><colgroup><col><col><col></colgroup><thead><tr><th align="center">Action</th><th align="center">MS Windows Command</th><th align="center">Unix Command</th></tr></thead><tbody><tr><td align="center">create</td><td align="center">md folder</td><td align="center">mkdir folder</td></tr><tr><td align="center">delete</td><td align="center">rd folder</td><td align="center">rmdir folder</td></tr><tr><td align="center">rename</td><td align="center">rename oldname newname</td><td align="center">mv oldname newname</td></tr></tbody></table></div><p>
+       </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2920678"></a>File and Directory Access Control</h3></div></div><div></div></div><p>
+       The network administrator is strongly advised to read foundational training manuals and reference materials
+       regarding file and directory permissions maintenance. Much can be achieved with the basic Unix permissions
+       without having to resort to more complex facilities like POSIX Access Control Lists (ACLs) or Extended
+       Attributes (EAs).
+       </p><p>
+       Unix/Linux file and directory access permissions involves setting three (3) primary sets of data and one (1) control set.
+       A Unix file listing looks as follows:-
+
+       </p><pre class="screen">
+       <tt class="prompt">jht@frodo:~/stuff&gt; </tt><b class="userinput"><tt>ls -la</tt></b>
+       total 632
+       drwxr-xr-x   13 jht   users      816 2003-05-12 22:56 .
+       drwxr-xr-x   37 jht   users     3800 2003-05-12 22:29 ..
+       d---------    2 jht   users       48 2003-05-12 22:29 muchado00
+       d--x--x--x    2 jht   users       48 2003-05-12 22:29 muchado01
+       dr-xr-xr-x    2 jht   users       48 2003-05-12 22:29 muchado02
+       drwxrwxrwx    2 jht   users       48 2003-05-12 22:29 muchado03
+       drw-rw-rw-    2 jht   users       48 2003-05-12 22:29 muchado04
+       d-w--w--w-    2 jht   users       48 2003-05-12 22:29 muchado05
+       dr--r--r--    2 jht   users       48 2003-05-12 22:29 muchado06
+       drwxrwxrwt    2 jht   users       48 2003-05-12 22:29 muchado07
+       drwsrwsrwx    2 jht   users       48 2003-05-12 22:29 muchado08
+       ----------    1 jht   users     1242 2003-05-12 22:31 mydata00.lst
+       ---x--x--x    1 jht   users     1674 2003-05-12 22:33 mydata01.lst
+       --w--w--w-    1 jht   users     7754 2003-05-12 22:33 mydata02.lst
+       --wx-wx-wx    1 jht   users   260179 2003-05-12 22:33 mydata03.lst
+       -r--r--r--    1 jht   users    21017 2003-05-12 22:32 mydata04.lst
+       -r-xr-xr-x    1 jht   users   206339 2003-05-12 22:32 mydata05.lst
+       -rw-rw-rw-    1 jht   users    41105 2003-05-12 22:32 mydata06.lst
+       -rwxrwxrwx    1 jht   users    19312 2003-05-12 22:32 mydata07.lst
+       <tt class="prompt">jht@frodo:~/stuff&gt;</tt>
+       </pre><p>
+       </p><p>
+       The columns above represent (from left to right): permissions, no blocks used, owner, group, size (bytes), access date, access time, file name.
+       </p><p>
+       The permissions field is made up of:
+
+       </p><pre class="programlisting">
+       <i><span class="comment"> JRV: Put this into a diagram of some sort</span></i>
+       [ type  ] [ users ] [ group ] [ others ]   [File, Directory Permissions]
+       [ d | l ] [ r w x ] [ r w x ] [ r w x  ]
+         |   |     | | |     | | |     | | |
+         |   |     | | |     | | |     | | |-----&gt; Can Execute, List files
+         |   |     | | |     | | |     | |-------&gt; Can Write,   Create files
+         |   |     | | |     | | |     |---------&gt; Can Read,    Read files
+         |   |     | | |     | | |---------------&gt; Can Execute, List files
+         |   |     | | |     | |-----------------&gt; Can Write,   Create files
+         |   |     | | |     |-------------------&gt; Can Read,    Read files
+         |   |     | | |-------------------------&gt; Can Execute, List files
+         |   |     | |---------------------------&gt; Can Write,   Create files
+         |   |     |-----------------------------&gt; Can Read,    Read files
+         |   |-----------------------------------&gt; Is a symbolic Link
+         |---------------------------------------&gt; Is a directory
+       </pre><p>
+       </p><p>
+       Any bit flag may be unset. An unset bit flag is the equivalent of 'Can NOT' and is represented as a '-' character.
+
+       </p><div class="example"><a name="id2920816"></a><p class="title"><b>Example 13.1. Example File</b></p><pre class="programlisting">
+               -rwxr-x---   Means: The owner (user) can read, write, execute
+                                   the group can read and execute
+                                   everyone else can NOT do anything with it
+               </pre></div><p>
+
+       </p><p>
+       Additional possibilities in the [type] field are: c = character device, b = block device, p = pipe device, s = Unix Domain Socket.
+       </p><p>
+       The letters `rwxXst' set permissions for the user, group and others as: read (r), write (w), execute (or access for directories) (x),
+       execute  only  if  the  file  is a directory or already has execute permission for some user (X), set user or group ID on execution (s),
+       sticky (t).
+       </p><p>
+       When the sticky bit is set on a directory, files in that directory may be unlinked (deleted) or renamed only by root or their owner. 
+       Without the sticky  bit, anyone able to write to the directory can delete or rename files. The sticky bit is commonly found on
+       directories, such as /tmp, that are world-writable.
+       </p><p>
+       When the set user or group ID bit (s) is set on a directory, then all files created within it will be owned by the user and/or
+       group whose 'set user or group' bit is set. This can be very helpful in setting up directories that for which it is desired that
+       all users who are in a group should be able to write to and read from a file, particularly when it is undesirable for that file
+       to be exclusively owned by a user who's primary group is not the group that all such users belong to.
+       </p><p>
+       When a directory is set <tt class="constant">drw-r-----</tt> this means that the owner can read and create (write) files in it, but because
+       the (x) execute flags are not set files can not be listed (seen) in the directory by anyone. The group can read files in the
+       directory but can NOT create new files. NOTE: If files in the directory are set to be readable and writable for the group, then
+       group members will be able to write to (or delete) them.
+       </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2920894"></a>Share Definition Access Controls</h2></div></div><div></div></div><p>
+The following parameters in the <tt class="filename">smb.conf</tt> file sections that define a share control or affect access controls.
+Before using any of the following options please refer to the man page for <tt class="filename">smb.conf</tt>.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2922074"></a>User and Group Based Controls</h3></div></div><div></div></div><p>
+       User and group based controls can prove very useful. In some situations it is distinctly desirable to affect all
+       file system operations as if a single user is doing this, the use of the <i class="parameter"><tt>force user</tt></i> and 
+       <i class="parameter"><tt>force group</tt></i> behaviour will achieve this. In other situations it may be necessary to affect a
+       paranoia level of control to ensure that only particular authorised persons will be able to access a share or
+       it's contents, here the use of the <i class="parameter"><tt>valid users</tt></i> or the <i class="parameter"><tt>invalid users</tt></i> may
+       be most useful.
+       </p><p>
+       As always, it is highly advisable to use the least difficult to maintain and the least ambiguous method for
+       controlling access. Remember, that when you leave the scene someone else will need to provide assistance and
+       if that person finds too great a mess, or if they do not understand what you have done then there is risk of
+       Samba being removed and an alternative solution being adopted.
+       </p><div class="table"><a name="id2922134"></a><p class="title"><b>Table 13.2. User and Group Based Controls</b></p><table summary="User and Group Based Controls" border="1"><colgroup><col><col></colgroup><thead><tr><th align="center">Control Parameter</th><th align="center">Description - Action - Notes</th></tr></thead><tbody><tr><td>admin users</td><td><p>
+                       List of users who will be granted administrative privileges on the share.
+                       They will do all file operations as the super-user (root).  
+                       Any user in this list will be able to do anything they like on the share,
+                       irrespective of file permissions.
+                       </p></td></tr><tr><td>force group</td><td><p>
+                       Specifies a UNIX group name that will be assigned as the default primary group
+                       for all users connecting to this service.
+                       </p></td></tr><tr><td>force user</td><td><p>
+                       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. Incorrect use can cause security problems.
+                       </p></td></tr><tr><td>guest ok</td><td><p>
+                       If this parameter is set for a service, then no password is required to connect to the service. Privileges will be 
+                       those of the  guest account.
+                       </p></td></tr><tr><td>invalid users</td><td><p>
+                       List of users that should not be allowed to login to this service.
+                       </p></td></tr><tr><td>only user</td><td><p>
+                       Controls whether connections with usernames not in the user list will be allowed.
+                       </p></td></tr><tr><td>read list</td><td><p>
+                       List of users that are given read-only access to a service. Users in this list
+                       will not be given write access, no matter what the  read only  option is set to. 
+                       </p></td></tr><tr><td>username</td><td><p>
+                       Refer to the <tt class="filename">smb.conf</tt> man page for more information - this is a complex and potentially misused parameter.
+                       </p></td></tr><tr><td>valid users</td><td><p>
+                       List of users that should be allowed to login to this service.
+                       </p></td></tr><tr><td>write list</td><td><p>
+                       List of users that are given read-write access to a service.
+                       </p></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2922346"></a>File and Directory Permissions Based Controls</h3></div></div><div></div></div><p>
+       The following file and directory permission based controls, if misused, can result in considerable difficulty to
+       diagnose the cause of mis-configuration. Use them sparingly and carefully. By gradually introducing each one by one
+       undesirable side-effects may be detected. In the event of a problem, always comment all of them out and then gradually
+       re-introduce them in a controlled fashion.
+       </p><div class="table"><a name="id2922367"></a><p class="title"><b>Table 13.3. File and Directory Permission Based Controls</b></p><table summary="File and Directory Permission Based Controls" border="1"><colgroup><col><col></colgroup><thead><tr><th align="center">Control Parameter</th><th align="center">Description - Action - Notes</th></tr></thead><tbody><tr><td>create mask</td><td><p>
+                       Refer to the <tt class="filename">smb.conf</tt> man page.
+                       </p></td></tr><tr><td>directory mask</td><td><p>
+                       The octal modes used when converting DOS modes to UNIX modes when creating UNIX directories.
+                       See also: directory security mask.
+                       </p></td></tr><tr><td>dos filemode</td><td><p>
+                       Enabling this parameter allows a user who has write access to the file to modify the permissions on it.
+                       </p></td></tr><tr><td>force create mode</td><td><p>
+                       This parameter specifies a set of UNIX mode bit permissions that will always be set on a file created by Samba.
+                       </p></td></tr><tr><td>force directory mode</td><td><p>
+                       This parameter specifies a set of UNIX mode bit permissions that will always be set on a directory created by Samba.
+                       </p></td></tr><tr><td>force directory security mode</td><td><p>
+                       Controls UNIX permission bits modified when a Windows NT client is manipulating UNIX permissions on a directory
+                       </p></td></tr><tr><td>force security mode</td><td><p>
+                       Controls UNIX permission bits modified when a Windows NT client manipulates UNIX permissions.
+                       </p></td></tr><tr><td>hide unreadable</td><td><p>
+                       Prevents clients from seeing the existence of files that cannot be read.
+                       </p></td></tr><tr><td>hide unwriteable files</td><td><p>
+                       Prevents clients from seeing the existence of files that cannot be written to. Unwriteable directories are shown as usual. 
+                       </p></td></tr><tr><td>nt acl support</td><td><p>
+                       This parameter controls whether smbd will attempt to map UNIX permissions into Windows NT access control lists.
+                       </p></td></tr><tr><td>security mask</td><td><p>
+                       Controls UNIX permission bits modified when a Windows NT client is manipulating the UNIX permissions on a file.
+                       </p></td></tr></tbody></table></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2922591"></a>Miscellaneous Controls</h3></div></div><div></div></div><p>
+       The following are documented because of the prevalence of administrators creating inadvertant barriers to file
+       access by not understanding the full implications of <tt class="filename">smb.conf</tt> file settings.
+       </p><div class="table"><a name="id2922614"></a><p class="title"><b>Table 13.4. Other Controls</b></p><table summary="Other Controls" border="1"><colgroup><col><col></colgroup><thead><tr><th align="center">Control Parameter</th><th align="center">Description - Action - Notes</th></tr></thead><tbody><tr><td>case sensitive, default case, short preserve case</td><td><p>
+                       This means that all file name lookup will be done in a case sensitive manner. 
+                       Files will be created with the precise filename Samba received from the MS Windows client.
+                       </p></td></tr><tr><td>csc policy</td><td><p>
+                       Client Side Caching Policy - parallels MS Windows client side file caching capabilities.
+                       </p></td></tr><tr><td>dont descend</td><td><p>
+                       Allows to specify a comma-delimited list of directories that the server should always show as empty.
+                       </p></td></tr><tr><td>dos filetime resolution</td><td><p>
+                       This option is mainly used as a compatibility option for Visual C++ when used against Samba shares.
+                       </p></td></tr><tr><td>dos filetimes</td><td><p>
+                       DOS and Windows allows users to change file time stamps if they can write to the file. POSIX semantics prevent this.
+                       This options allows DOS and Windows behaviour.
+                       </p></td></tr><tr><td>fake oplocks</td><td><p>
+                       Oplocks are the way that SMB clients get permission from a server to locally cache file operations. If a server grants an
+                       oplock then the client is free to assume that it is the only one accessing the file and it will aggressively cache file data.
+                       </p></td></tr><tr><td>hide dot files, hide files, veto files</td><td><p>
+                       Note: MS Windows Explorer allows over-ride of files marked as hidden so they will still be visible.
+                       </p></td></tr><tr><td>read only</td><td><p>
+                       If this parameter is yes, then users of a service may not create or modify files in the service's directory.
+                       </p></td></tr><tr><td>veto files</td><td><p>
+                       List of files and directories that are neither visible nor accessible.
+                       </p></td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2922807"></a>Access Controls on Shares</h2></div></div><div></div></div><p>
+       This section deals with how to configure Samba per share access control restrictions.
+       By default, Samba sets no restrictions on the share itself. Restrictions on the share itself
+       can be set on MS Windows NT4/200x/XP shares. This can be a very effective way to limit who can
+       connect to a share. In the absence of specific restrictions the default setting is to allow
+       the global user <tt class="constant">Everyone</tt> Full Control (ie: Full control, Change and Read).
+       </p><p>
+       At this time Samba does NOT provide a tool for configuring access control setting on the Share
+       itself. Samba does have the capacity to store and act on access control settings, but  the only
+       way to create those settings is to use either the NT4 Server Manager or the Windows 200x MMC for
+       Computer Management.
+       </p><p>
+       Samba stores the per share access control settings in a file called <tt class="filename">share_info.tdb</tt>.
+       The location of this file on your system will depend on how samba was compiled. The default location
+       for Samba's tdb files is under <tt class="filename">/usr/local/samba/var</tt>. If the <tt class="filename">tdbdump</tt>
+       utility has been compiled and installed on your system, then you can examine the contents of this file
+       by: <b class="userinput"><tt>tdbdump share_info.tdb</tt></b>.
+       </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2922879"></a>Share Permissions Management</h3></div></div><div></div></div><p>
+               The best tool for the task is platform dependant. Choose the best tool for your environment.
+               </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2922892"></a>Windows NT4 Workstation/Server</h4></div></div><div></div></div><p>
+                       The tool you need to use to manage share permissions on a Samba server is the NT Server Manager.
+                       Server Manager is shipped with Windows NT4 Server products but not with Windows NT4 Workstation.
+                       You can obtain the NT Server Manager for MS Windows NT4 Workstation from Microsoft - see details below.
+                       </p><div class="procedure"><p class="title"><b>Procedure 13.1. Instructions</b></p><ol type="1"><li><p>
+                       Launch the <span class="application">NT4 Server Manager</span>, click on the Samba server you want to administer, then from the menu
+                       select <span class="guimenu">Computer</span>, then click on the <span class="guimenuitem">Shared Directories</span> entry.
+                       </p></li><li><p>
+                       Now click on the share that you wish to manage, then click on the <span class="guilabel">Properties</span> tab, next click on
+                       the <span class="guilabel">Permissions</span> tab. Now you can add or change access control settings as you wish.
+                       </p></li></ol></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2922975"></a>Windows 200x/XP</h4></div></div><div></div></div><p>
+                       On <span class="application">MS Windows NT4/200x/XP</span> system access control lists on the share itself are set using native
+                       tools, usually from filemanager. For example, in Windows 200x: right click on the shared folder,
+                       then select <span class="guimenuitem">Sharing</span>, then click on <span class="guilabel">Permissions</span>. The default 
+                       Windows NT4/200x permission allows <span class="emphasis"><em>Everyone</em></span> Full Control on the Share.
+                       </p><p>
+                       MS Windows 200x and later all comes with a tool called the <span class="application">Computer Management</span> snap-in for the
+                       Microsoft Management Console (MMC). This tool is located by clicking on <tt class="filename">Control Panel -&gt;
+                       Administrative Tools -&gt; Computer Management</tt>.
+                       </p><div class="procedure"><p class="title"><b>Procedure 13.2. Instructions</b></p><ol type="1"><li><p>
+                               After launching the MMC with the Computer Management snap-in, click on the menu item <span class="guimenuitem">Action</span>,
+                               select <span class="guilabel">Connect to another computer</span>. If you are not logged onto a domain you will be prompted
+                               to enter a domain login user identifier and a password. This will authenticate you to the domain.
+                               If you where already logged in with administrative privilege this step is not offered.
+                       </p></li><li><p>
+                       If the Samba server is not shown in the <span class="guilabel">Select Computer</span> box, then type in the name of the target
+                       Samba server in the field <span class="guilabel">Name:</span>. Now click on the <span class="guibutton">[+]</span> next to 
+                       <span class="guilabel">System Tools</span>, then on the <span class="guibutton">[+]</span> next to <span class="guilabel">Shared Folders</span> in the 
+                       left panel.
+                       </p></li><li><p>
+                       Now in the right panel, double-click on the share you wish to set access control permissions on.
+                       Then click on the tab <span class="guilabel">Share Permissions</span>. It is now possible to add access control entities
+                       to the shared folder. Do NOT forget to set what type of access (full control, change, read) you
+                       wish to assign for each entry.
+                       </p></li></ol></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+                       Be careful. If you take away all permissions from the <tt class="constant">Everyone</tt> user without removing this user
+                       then effectively no user will be able to access the share. This is a result of what is known as
+                       ACL precedence. ie: Everyone with <span class="emphasis"><em>no access</em></span> means that MaryK who is part of the group 
+                       <tt class="constant">Everyone</tt> will have no access even if this user is given explicit full control access.
+                       </p></div></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2923178"></a>MS Windows Access Control Lists and Unix Interoperability</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923186"></a>Managing UNIX permissions Using NT Security Dialogs</h3></div></div><div></div></div><p>Windows NT clients can use their native security settings 
+               dialog box to view and modify the underlying UNIX permissions.</p><p>Note that this ability is careful not to compromise 
+               the security of the UNIX host Samba is running on, and 
+               still obeys all the file permission rules that a Samba 
+               administrator can set.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+               All access to Unix/Linux system file via Samba is controlled at
+               the operating system file access control level. When trying to
+               figure out file access problems it is vitally important to identify
+               the identity of the Windows user as it is presented by Samba at
+               the point of file access. This can best be determined from the
+               Samba log files.
+               </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923224"></a>Viewing File Security on a Samba Share</h3></div></div><div></div></div><p>From an NT4/2000/XP client, single-click with the right 
+               mouse button on any file or directory in a Samba mounted 
+               drive letter or UNC path. When the menu pops-up, click 
+               on the <span class="guilabel">Properties</span> entry at the bottom of 
+               the menu. This brings up the file properties dialog
+               box. Click on the tab <span class="guilabel">Security</span> and you 
+               will see three buttons, <span class="guibutton">Permissions</span>,      
+               <span class="guibutton">Auditing</span>, and <span class="guibutton">Ownership</span>. 
+               The <span class="guibutton">Auditing</span> button will cause either 
+               an error message <span class="errorname">A requested privilege is not held 
+               by the client</span> to appear if the user is not the 
+               NT Administrator, or a dialog which is intended to allow an 
+               Administrator to add auditing requirements to a file if the 
+               user is logged on as the NT Administrator. This dialog is 
+               non-functional with a Samba share at this time, as the only 
+               useful button, the <span class="guibutton">Add</span> button will not currently 
+               allow a list of users to be seen.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923303"></a>Viewing file ownership</h3></div></div><div></div></div><p>Clicking on the <span class="guibutton">Ownership</span> button 
+               brings up a dialog box telling you who owns the given file. The 
+               owner name will be of the form :</p><p><b class="command">&quot;SERVER\user (Long name)&quot;</b></p><p>Where <i class="replaceable"><tt>SERVER</tt></i> is the NetBIOS name of 
+               the Samba server, <i class="replaceable"><tt>user</tt></i> is the user name of 
+               the UNIX user who owns the file, and <i class="replaceable"><tt>(Long name)</tt></i>
+               is the descriptive string identifying the user (normally found in the
+               GECOS field of the UNIX password database). Click on the 
+               <span class="guibutton">Close </span> button to remove this dialog.</p><p>If the parameter <i class="parameter"><tt>nt acl support</tt></i>
+               is set to <tt class="constant">false</tt> then the file owner will 
+               be shown as the NT user <tt class="constant">&quot;Everyone&quot;</tt>.</p><p>The <span class="guibutton">Take Ownership</span> button will not allow 
+               you to change the ownership of this file to yourself (clicking on 
+               it will display a dialog box complaining that the user you are 
+               currently logged onto the NT client cannot be found). The reason 
+               for this is that changing the ownership of a file is a privileged 
+               operation in UNIX, available only to the <span class="emphasis"><em>root</em></span> 
+               user. As clicking on this button causes NT to attempt to change 
+               the ownership of a file to the current user logged into the NT 
+               client this will not work with Samba at this time.</p><p>There is an NT chown command that will work with Samba 
+               and allow a user with Administrator privilege connected 
+               to a Samba server as root to change the ownership of 
+               files on both a local NTFS filesystem or remote mounted NTFS 
+               or Samba drive. This is available as part of the <span class="application">Seclib
+               </span> NT security library written by Jeremy Allison of 
+               the Samba Team, available from the main Samba ftp site.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923425"></a>Viewing File or Directory Permissions</h3></div></div><div></div></div><p>The third button is the <span class="guibutton">Permissions</span> 
+               button. Clicking on this brings up a dialog box that shows both 
+               the permissions and the UNIX owner of the file or directory. 
+               The owner is displayed in the form :</p><p><b class="command">&quot;<i class="replaceable"><tt>SERVER</tt></i>\
+                               <i class="replaceable"><tt>user</tt></i> 
+                               <i class="replaceable"><tt>(Long name)</tt></i>&quot;</b></p><p>Where <i class="replaceable"><tt>SERVER</tt></i> is the NetBIOS name of 
+               the Samba server, <i class="replaceable"><tt>user</tt></i> is the user name of 
+               the UNIX user who owns the file, and <i class="replaceable"><tt>(Long name)</tt></i>
+               is the descriptive string identifying the user (normally found in the
+               GECOS field of the UNIX password database).</p><p>If the parameter <i class="parameter"><tt>nt acl support</tt></i>
+               is set to <tt class="constant">false</tt> then the file owner will 
+               be shown as the NT user <tt class="constant">&quot;Everyone&quot;</tt> and the 
+               permissions will be shown as NT &quot;Full Control&quot;.</p><p>The permissions field is displayed differently for files 
+               and directories, so I'll describe the way file permissions 
+               are displayed first.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2923516"></a>File Permissions</h4></div></div><div></div></div><p>The standard UNIX user/group/world triplet and 
+                       the corresponding &quot;read&quot;, &quot;write&quot;, &quot;execute&quot; permissions 
+                       triplets are mapped by Samba into a three element NT ACL 
+                       with the 'r', 'w', and 'x' bits mapped into the corresponding 
+                       NT permissions. The UNIX world permissions are mapped into 
+                       the global NT group <tt class="constant">Everyone</tt>, followed 
+                       by the list of permissions allowed for UNIX world. The UNIX 
+                       owner and group permissions are displayed as an NT 
+                       <span class="guiicon">user</span> icon and an NT <span class="guiicon">local 
+                       group</span> icon respectively followed by the list 
+                       of permissions allowed for the UNIX user and group.</p><p>As many UNIX permission sets don't map into common 
+                       NT names such as <tt class="constant">read</tt>, <tt class="constant">
+                       &quot;change&quot;</tt> or <tt class="constant">full control</tt> then 
+                       usually the permissions will be prefixed by the words <tt class="constant">
+                       &quot;Special Access&quot;</tt> in the NT display list.</p><p>But what happens if the file has no permissions allowed 
+                       for a particular UNIX user group or world component ? In order 
+                       to  allow &quot;no permissions&quot; to be seen and modified then Samba 
+                       overloads the NT <b class="command">&quot;Take Ownership&quot;</b> ACL attribute 
+                       (which has no meaning in UNIX) and reports a component with 
+                       no permissions as having the NT <b class="command">&quot;O&quot;</b> bit set. 
+                       This was chosen of course to make it look like a zero, meaning 
+                       zero permissions. More details on the decision behind this will 
+                       be given below.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2923608"></a>Directory Permissions</h4></div></div><div></div></div><p>Directories on an NT NTFS file system have two 
+                       different sets of permissions. The first set of permissions 
+                       is the ACL set on the directory itself, this is usually displayed 
+                       in the first set of parentheses in the normal <tt class="constant">&quot;RW&quot;</tt> 
+                       NT style. This first set of permissions is created by Samba in 
+                       exactly the same way as normal file permissions are, described 
+                       above, and is displayed in the same way.</p><p>The second set of directory permissions has no real meaning 
+                       in the UNIX permissions world and represents the <tt class="constant">
+                       inherited</tt> permissions that any file created within 
+                       this directory would inherit.</p><p>Samba synthesises these inherited permissions for NT by 
+                       returning as an NT ACL the UNIX permission mode that a new file 
+                       created by Samba on this share would receive.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923653"></a>Modifying file or directory permissions</h3></div></div><div></div></div><p>Modifying file and directory permissions is as simple 
+               as changing the displayed permissions in the dialog box, and 
+               clicking the <span class="guibutton">OK</span> button. However, there are 
+               limitations that a user needs to be aware of, and also interactions 
+               with the standard Samba permission masks and mapping of DOS 
+               attributes that need to also be taken into account.</p><p>If the parameter <i class="parameter"><tt>nt acl support</tt></i>
+               is set to <tt class="constant">false</tt> then any attempt to set 
+               security permissions will fail with an <span class="errorname">&quot;Access Denied&quot;
+               </span> message.</p><p>The first thing to note is that the <span class="guibutton">&quot;Add&quot;</span> 
+               button will not return a list of users in Samba (it will give 
+               an error message of <span class="errorname">The remote procedure call failed 
+               and did not execute</span>). This means that you can only 
+               manipulate the current user/group/world permissions listed in 
+               the dialog box. This actually works quite well as these are the 
+               only permissions that UNIX actually has.</p><p>If a permission triplet (either user, group, or world) 
+               is removed from the list of permissions in the NT dialog box, 
+               then when the <span class="guibutton">OK</span> button is pressed it will 
+               be applied as &quot;no permissions&quot; on the UNIX side. If you then 
+               view the permissions again the &quot;no permissions&quot; entry will appear 
+               as the NT <b class="command">&quot;O&quot;</b> flag, as described above. This 
+               allows you to add permissions back to a file or directory once 
+               you have removed them from a triplet component.</p><p>As UNIX supports only the &quot;r&quot;, &quot;w&quot; and &quot;x&quot; bits of 
+               an NT ACL then if other NT security attributes such as &quot;Delete 
+               access&quot; are selected then they will be ignored when applied on 
+               the Samba server.</p><p>When setting permissions on a directory the second 
+               set of permissions (in the second set of parentheses) is 
+               by default applied to all files within that directory. If this 
+               is not what you want you must uncheck the <span class="guilabel">Replace 
+               permissions on existing files</span> checkbox in the NT 
+               dialog before clicking <span class="guibutton">OK</span>.</p><p>If you wish to remove all permissions from a 
+               user/group/world  component then you may either highlight the 
+               component and click the <span class="guibutton">Remove</span> button, 
+               or set the component to only have the special <tt class="constant">Take
+               Ownership</tt> permission (displayed as <b class="command">&quot;O&quot;
+               </b>) highlighted.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2923805"></a>Interaction with the standard Samba create mask 
+               parameters</h3></div></div><div></div></div><p>There are four parameters 
+               to control interaction with the standard Samba create mask parameters.
+               These are :
+
+               </p><table class="simplelist" border="0" summary="Simple list"><tr><td><i class="parameter"><tt>security mask</tt></i></td></tr><tr><td><i class="parameter"><tt>force security mode</tt></i></td></tr><tr><td><i class="parameter"><tt>directory security mask</tt></i></td></tr><tr><td><i class="parameter"><tt>force directory security mode</tt></i></td></tr></table><p>
+
+               </p><p>Once a user clicks <span class="guibutton">OK</span> to apply the 
+               permissions Samba maps the given permissions into a user/group/world 
+               r/w/x triplet set, and then will check the changed permissions for a 
+               file against the bits set in the <a href="smb.conf.5.html#SECURITYMASK" target="_top"> 
+               <i class="parameter"><tt>security mask</tt></i></a> parameter. Any bits that 
+               were changed that are not set to '1' in this parameter are left alone 
+               in the file permissions.</p><p>Essentially, zero bits in the <i class="parameter"><tt>security mask</tt></i>
+               mask may be treated as a set of bits the user is <span class="emphasis"><em>not</em></span> 
+               allowed to change, and one bits are those the user is allowed to change.
+               </p><p>If not set explicitly this parameter is set to the same value as 
+               the <a href="smb.conf.5.html#CREATEMASK" target="_top"><i class="parameter"><tt>create mask
+               </tt></i></a> parameter. To allow a user to modify all the
+               user/group/world permissions on a file, set this parameter 
+               to 0777.</p><p>Next Samba checks the changed permissions for a file against 
+               the bits set in the <a href="smb.conf.5.html#FORCESECURITYMODE" target="_top">
+               <i class="parameter"><tt>force security mode</tt></i></a> parameter. Any bits 
+               that were changed that correspond to bits set to '1' in this parameter 
+               are forced to be set.</p><p>Essentially, bits set in the <i class="parameter"><tt>force security mode
+               </tt></i> parameter may be treated as a set of bits that, when 
+               modifying security on a file, the user has always set to be 'on'.</p><p>If not set explicitly this parameter is set to the same value 
+               as the <a href="smb.conf.5.html#FORCECREATEMODE" target="_top"><i class="parameter"><tt>force 
+               create mode</tt></i></a> parameter.
+               To allow a user to modify all the user/group/world permissions on a file
+               with no restrictions set this parameter to 000.</p><p>The <i class="parameter"><tt>security mask</tt></i> and <i class="parameter"><tt>force 
+               security mode</tt></i> parameters are applied to the change 
+               request in that order.</p><p>For a directory Samba will perform the same operations as 
+               described above for a file except using the parameter <i class="parameter"><tt>
+               directory security mask</tt></i> instead of <i class="parameter"><tt>security 
+               mask</tt></i>, and <i class="parameter"><tt>force directory security mode
+               </tt></i> parameter instead of <i class="parameter"><tt>force security mode
+               </tt></i>.</p><p>The <i class="parameter"><tt>directory security mask</tt></i> parameter 
+               by default is set to the same value as the <i class="parameter"><tt>directory mask
+               </tt></i> parameter and the <i class="parameter"><tt>force directory security 
+               mode</tt></i> parameter by default is set to the same value as 
+               the <i class="parameter"><tt>force directory mode</tt></i> parameter. </p><p>In this way Samba enforces the permission restrictions that 
+               an administrator can set on a Samba share, whilst still allowing users 
+               to modify the permission bits within that restriction.</p><p>If you want to set up a share that allows users full control
+               in modifying the permission bits on their files and directories and
+               doesn't force any particular bits to be set 'on', then set the following
+               parameters in the <tt class="filename">smb.conf</tt> file in that share specific section :
+               </p><table class="simplelist" border="0" summary="Simple list"><tr><td><i class="parameter"><tt>security mask = 0777</tt></i></td></tr><tr><td><i class="parameter"><tt>force security mode = 0</tt></i></td></tr><tr><td><i class="parameter"><tt>directory security mask = 0777</tt></i></td></tr><tr><td><i class="parameter"><tt>force directory security mode = 0</tt></i></td></tr></table></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2924134"></a>Interaction with the standard Samba file attribute 
+               mapping</h3></div></div><div></div></div><p>Samba maps some of the DOS attribute bits (such as &quot;read 
+               only&quot;) into the UNIX permissions of a file. This means there can 
+               be a conflict between the permission bits set via the security 
+               dialog and the permission bits set by the file attribute mapping.
+               </p><p>One way this can show up is if a file has no UNIX read access
+               for the owner it will show up as &quot;read only&quot; in the standard 
+               file attributes tabbed dialog. Unfortunately this dialog is
+               the same one that contains the security info in another tab.</p><p>What this can mean is that if the owner changes the permissions
+               to allow themselves read access using the security dialog, clicks
+               <span class="guibutton">OK</span> to get back to the standard attributes tab 
+               dialog, and then clicks <span class="guibutton">OK</span> on that dialog, then 
+               NT will set the file permissions back to read-only (as that is what 
+               the attributes still say in the dialog). This means that after setting 
+               permissions and clicking <span class="guibutton">OK</span> to get back to the 
+               attributes dialog you should always hit <span class="guibutton">Cancel</span> 
+               rather than <span class="guibutton">OK</span> to ensure that your changes 
+               are not overridden.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2924210"></a>Common Errors</h2></div></div><div></div></div><p>
+File, Directory and Share access problems are very common on the mailing list. The following
+are examples taken from the mailing list in recent times.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2924224"></a>Users can not write to a public share</h3></div></div><div></div></div><p>
+       &#8220;<span class="quote">
+       We are facing some troubles with file / directory permissions. I can log on the domain as admin user(root),
+       and there's a public share, on which everyone needs to have permission to create / modify files, but only
+       root can change the file, no one else can. We need to constantly go to server to
+       <b class="userinput"><tt>chgrp -R users *</tt></b> and <b class="userinput"><tt>chown -R nobody *</tt></b> to allow others users to change the file.
+       </span>&#8221;
+       </p><p>
+       There are many ways to solve this problem, here are a few hints:
+       </p><div class="procedure"><p class="title"><b>Procedure 13.3. Example Solution:</b></p><ol type="1"><li><p>
+                       Go to the top of the directory that is shared
+                       </p></li><li><p>
+                       Set the ownership to what ever public owner and group you want
+                       </p><pre class="programlisting">
+                       find 'directory_name' -type d -exec chown user.group {}\;
+                       find 'directory_name' -type d -exec chmod 6775 'directory_name'
+                       find 'directory_name' -type f -exec chmod 0775 {} \;
+                       find 'directory_name' -type f -exec chown user.group {}\;
+                       </pre><p>
+                       </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+                       The above will set the 'sticky bit' on all directories. Read your
+                       Unix/Linux man page on what that does. It causes the OS to assign 
+                       to all files created in the directories the ownership of the 
+                       directory.
+                       </p></div></li><li><p>
+
+                       Directory is: <i class="replaceable"><tt>/foodbar</tt></i>
+                       </p><pre class="screen">
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>chown jack.engr /foodbar</tt></b>
+                       </pre><p>
+                       </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+                               </p><p>This is the same as doing:</p><p>
+                               </p><pre class="screen">
+                                       <tt class="prompt">$ </tt><b class="userinput"><tt>chown jack /foodbar</tt></b>
+                                       <tt class="prompt">$ </tt><b class="userinput"><tt>chgrp engr /foodbar</tt></b>
+                               </pre><p>
+                       </p></div></li><li><p>Now do: 
+
+                       </p><pre class="screen">
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>chmod 6775 /foodbar</tt></b>
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>ls -al /foodbar/..</tt></b>
+                       </pre><p>
+
+                       </p><p>You should see:
+                       </p><pre class="screen">
+                               drwsrwsr-x  2 jack  engr    48 2003-02-04 09:55 foodbar
+                       </pre><p>
+                       </p></li><li><p>Now do:
+                       </p><pre class="screen">
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>su - jill</tt></b>
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>cd /foodbar</tt></b>
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>touch Afile</tt></b>
+                               <tt class="prompt">$ </tt><b class="userinput"><tt>ls -al</tt></b>
+                       </pre><p>
+               </p><p>
+               You should see that the file <tt class="filename">Afile</tt> created by Jill will have ownership
+               and permissions of Jack, as follows:
+               </p><pre class="screen">
+               -rw-r--r--  1 jack  engr     0 2003-02-04 09:57 Afile
+               </pre><p>
+               </p></li><li><p>
+               Now in your <tt class="filename">smb.conf</tt> for the share add:
+               </p><pre class="programlisting">
+               force create mode = 0775
+               force directory mode = 6775
+               </pre><p>
+               </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+               The above are only needed <span class="emphasis"><em>if</em></span> your users are <span class="emphasis"><em>not</em></span> members of the group
+               you have used. ie: Within the OS do not have write permission on the directory.
+               </p></div><p>
+               An alternative is to set in the <tt class="filename">smb.conf</tt> entry for the share:
+               </p><pre class="programlisting">
+               force user = jack
+               force group = engr
+               </pre><p>
+               </p></li></ol></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2924604"></a>I have set force user and Samba still makes <span class="emphasis"><em>root</em></span> the owner of all the files
+                       I touch!</h3></div></div><div></div></div><p>
+                       When you have a user in 'admin users', Samba will always do file operations for
+                       this user as <span class="emphasis"><em>root</em></span>, even if <i class="parameter"><tt>force user</tt></i> has been set.
+               </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groupmapping.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="locking.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 12. Mapping MS Windows and Unix Groups </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 14. File and Record Locking</td></tr></table></div></body></html>

diff --git a/docs/htmldocs/AdvancedNetworkManagement.html b/docs/htmldocs/AdvancedNetworkManagement.html
new file mode 100644 (file)
index 0000000..296c684
--- /dev/null
+++ b/docs/htmldocs/AdvancedNetworkManagement.html
@@ -0,0 +1,224 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 22. Advanced Network Management</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="winbind.html" title="Chapter 21. Integrated Logon Support using Winbind"><link rel="next" href="PolicyMgmt.html" title="Chapter 23. System and Account Policies"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 22. Advanced Network Management</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="winbind.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="PolicyMgmt.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="AdvancedNetworkManagement"></a>Chapter 22. Advanced Network Management</h2></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jht@samba.org">jht@samba.org</a>&gt;</tt></p></div></div></div></div><div><p class="pubdate">April 3 2003</p></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="AdvancedNetworkManagement.html#id2984570">Features and Benefits</a></dt><dt><a href="AdvancedNetworkManagement.html#id2984759">Remote Server Administration</a></dt><dt><a href="AdvancedNetworkManagement.html#id2984858">Remote Desktop Management</a></dt><dd><dl><dt><a href="AdvancedNetworkManagement.html#id2984876">Remote Management from NoMachines.Com</a></dt></dl></dd><dt><a href="AdvancedNetworkManagement.html#id2985087">Network Logon Script Magic</a></dt><dd><dl><dt><a href="AdvancedNetworkManagement.html#id2985283">Adding printers without user intervention</a></dt></dl></dd><dt><a href="AdvancedNetworkManagement.html#id2985316">Common Errors</a></dt></dl></div><p>
+This section documents peripheral issues that are of great importance to network
+administrators who want to improve network resource access control, to automate the user
+environment, and to make their lives a little easier.
+</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2984570"></a>Features and Benefits</h2></div></div><div></div></div><p>
+Often the difference between a working network environment and a well appreciated one can
+best be measured by the <span class="emphasis"><em>little things</em></span> that makes everything work more
+harmoniously. A key part of every network environment solution is the ability to remotely
+manage MS Windows workstations, to remotely access the Samba server, to provide customised
+logon scripts, as well as other house keeping activities that help to sustain more reliable
+network operations.
+</p><p>
+This chapter presents information on each of these area. They are placed here, and not in
+other chapters, for ease of reference.
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2984759"></a>Remote Server Administration</h2></div></div><div></div></div><p>
+<span class="emphasis"><em>How do I get 'User Manager' and 'Server Manager'?</em></span>
+</p><p>
+       Since I don't need to buy an <span class="application">NT4 Server</span>, how do I get the 'User Manager for Domains',
+the 'Server Manager'?
+</p><p>
+Microsoft distributes a version of these tools called nexus for installation 
+on <span class="application">Windows 9x / Me</span> systems.  The tools set includes:
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td>Server Manager</td></tr><tr><td>User Manager for Domains</td></tr><tr><td>Event Viewer</td></tr></table><p>
+Click here to download the archived file <a href="ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE" target="_top">ftp://ftp.microsoft.com/Softlib/MSLFILES/NEXUS.EXE</a>
+</p><p>
+The <span class="application">Windows NT 4.0</span> version of the 'User Manager for 
+Domains' and 'Server Manager' are available from Microsoft via ftp 
+from <a href="ftp://ftp.microsoft.com/Softlib/MSLFILES/SRVTOOLS.EXE" target="_top">ftp://ftp.microsoft.com/Softlib/MSLFILES/SRVTOOLS.EXE</a>
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2984858"></a>Remote Desktop Management</h2></div></div><div></div></div><p>
+There are a number of possible remote desktop management solutions that range from free
+through costly. Do not let that put you off. Sometimes the most costly solutions is the
+most cost effective. In any case, you will need to draw your own conclusions as to which
+is the best tool in your network environment.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2984876"></a>Remote Management from NoMachines.Com</h3></div></div><div></div></div><p>
+       The following information was posted to the Samba mailing list at Apr 3 23:33:50 GMT 2003.
+       It is presented in slightly edited form (with author details omitted for privacy reasons).
+       The entire answer is reproduced below with some comments removed.
+       </p><p>
+</p><pre class="screen">
+&gt; I have a wonderful linux/samba server running as PDC for a network.
+&gt; Now I would like to add remote desktop capabilities so that
+&gt; users outside could login to the system and get their desktop up from
+&gt; home or another country..
+&gt;
+&gt; Is there a way to accomplish this? Do I need a windows terminal server?
+&gt; Do I need to configure it so that it is a member of the domain or a
+&gt; BDC,PDC? Are there any hacks for MS Windows XP to enable remote login
+&gt; even if the computer is in a domain?
+&gt;
+&gt; Any ideas/experience would be appreciated :)
+</pre><p>
+</p><p>
+       Answer provided: Check out the new offer from NoMachine, &quot;NX&quot; software:
+       <a href="http://www.nomachine.com/" target="_top">http://www.nomachine.com/</a>.
+       </p><p>
+       It implements a very easy-to-use interface to the remote X protocol as
+       well as incorporating VNC/RFB and rdesktop/RDP into it, but at a speed
+       performance much better than anything you may have ever seen...
+       </p><p>
+       Remote X is not new at all -- but what they did achieve successfully is
+       a new way of compression and caching technologies which makes the thing
+       fast enough to run even over slow modem/ISDN connections.
+       </p><p>
+       I could test drive their (public) RedHat machine in Italy, over a loaded
+       internet connection, with enabled thumbnail previews in KDE konqueror
+       which popped up immediately on &quot;mouse-over&quot;. From inside that (remote X)
+       session I started a rdesktop session on another, a Windows XP machine.
+       To test the performance, I played Pinball. I am proud to announce here
+       that my score was 631750 points at first try...
+       </p><p>
+       NX performs better on my local LAN than any of the other &quot;pure&quot;
+       connection methods I am using from time to time: TightVNC, rdesktop or
+       remote X. It is even faster than a direct crosslink connection between
+       two nodes.
+       </p><p>
+       I even got sound playing from the remote X app to my local boxes, and
+       had a working &quot;copy'n'paste&quot; from an NX  window (running a KDE session
+       in Italy) to my Mozilla mailing agent... These guys are certainly doing
+       something right!
+       </p><p>
+       I recommend to test drive NX to anybody with a only a remote interest
+       in remote computing
+       <a href="http://www.nomachine.com/testdrive.php" target="_top">http://www.nomachine.com/testdrive.php</a>.
+       </p><p>
+       Just download the free of charge client software (available for RedHat,
+       SuSE, Debian and Windows) and be up and running within 5 minutes (they
+       need to send you your account data, though, because you are assigned
+       a real Unix account on their testdrive.nomachine.com box...
+       </p><p>
+       They plan to get to the point were you can have NX application servers
+       running as a cluster of nodes, and users simply start an NX session locally,
+       and can select applications to run transparently (apps may even run on
+       another NX node, but pretend to be on the same as used for initial login,
+       because it displays in the same window.... well, you also can run it
+       fullscreen, and after a short time you forget that it is a remote session
+       at all).
+       </p><p>
+       Now the best thing at the end: all the core compression and caching
+       technologies are released under the GPL and available as source code
+       to anybody who wants to build on it! These technologies are working,
+       albeit started from the command line only (and very inconvenient to
+       use in order to get a fully running remote X session up and running....)
+       </p><p>
+       To answer your questions:
+       </p><div class="itemizedlist"><ul type="disc"><li><p>
+               You don't need to install a terminal server; XP has RDP support built in.
+               </p></li><li><p>
+               NX is much cheaper than Citrix -- and comparable in performance, probably faster
+               </p></li><li><p>
+               You don't need to hack XP -- it just works
+               </p></li><li><p>
+               You log into the XP box from remote transparently (and I think there is no
+               need to change anything to get a connection, even if authentication is against a domain)
+               </p></li><li><p>
+               The NX core technologies are all Open Source and released under the GPL --
+               you can today use a (very inconvenient) commandline to use it at no cost,
+               but you can buy a comfortable (proprietary) NX GUI frontend for money
+               </p></li><li><p>
+               NoMachine are encouraging and offering help to OSS/Free Software implementations
+               for such a frontend too, even if it means competition to them (they have written
+               to this effect even to the LTSP, KDE and GNOME developer mailing lists)
+               </p></li></ul></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2985087"></a>Network Logon Script Magic</h2></div></div><div></div></div><p>
+This section needs work. Volunteer contributions most welcome. Please send your patches or updates
+to <a href="mailto:jht@samba.org" target="_top">John Terpstra</a>.
+</p><p>
+There are several opportunities for creating a custom network startup configuration environment.
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td>No Logon Script</td></tr><tr><td>Simple universal Logon Script that applies to all users</td></tr><tr><td>Use of a conditional Logon Script that applies per user or per group attributes</td></tr><tr><td>Use of Samba's Preexec and Postexec functions on access to the NETLOGON share to create
+       a custom Logon Script and then execute it.</td></tr><tr><td>User of a tool such as KixStart</td></tr></table><p>
+The Samba source code tree includes two logon script generation/execution tools.
+See <tt class="filename">examples</tt> directory <tt class="filename">genlogon</tt> and
+<tt class="filename">ntlogon</tt> subdirectories.
+</p><p>
+The following listings are from the genlogon directory.
+</p><p>
+This is the <tt class="filename">genlogon.pl</tt> file:
+
+</p><pre class="programlisting">
+       #!/usr/bin/perl
+       #
+       # genlogon.pl
+       #
+       # Perl script to generate user logon scripts on the fly, when users
+       # connect from a Windows client.  This script should be called from smb.conf
+       # with the %U, %G and %L parameters. I.e:
+       #
+       #       root preexec = genlogon.pl %U %G %L
+       #
+       # The script generated will perform
+       # the following:
+       #
+       # 1. Log the user connection to /var/log/samba/netlogon.log
+       # 2. Set the PC's time to the Linux server time (which is maintained
+       #    daily to the National Institute of Standard's Atomic clock on the
+       #    internet.
+       # 3. Connect the user's home drive to H: (H for Home).
+       # 4. Connect common drives that everyone uses.
+       # 5. Connect group-specific drives for certain user groups.
+       # 6. Connect user-specific drives for certain users.
+       # 7. Connect network printers.
+
+       # Log client connection
+       #($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
+       ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
+       open LOG, &quot;&gt;&gt;/var/log/samba/netlogon.log&quot;;
+       print LOG &quot;$mon/$mday/$year $hour:$min:$sec - User $ARGV[0] logged into $ARGV[1]\n&quot;;
+       close LOG;
+
+       # Start generating logon script
+       open LOGON, &quot;&gt;/shared/netlogon/$ARGV[0].bat&quot;;
+       print LOGON &quot;\@ECHO OFF\r\n&quot;;
+
+       # Connect shares just use by Software Development group
+       if ($ARGV[1] eq &quot;SOFTDEV&quot; || $ARGV[0] eq &quot;softdev&quot;)
+       {
+               print LOGON &quot;NET USE M: \\\\$ARGV[2]\\SOURCE\r\n&quot;;
+       }
+
+       # Connect shares just use by Technical Support staff
+       if ($ARGV[1] eq &quot;SUPPORT&quot; || $ARGV[0] eq &quot;support&quot;)
+       {
+               print LOGON &quot;NET USE S: \\\\$ARGV[2]\\SUPPORT\r\n&quot;;
+       }
+
+       # Connect shares just used by Administration staff
+       If ($ARGV[1] eq &quot;ADMIN&quot; || $ARGV[0] eq &quot;admin&quot;)
+       {
+               print LOGON &quot;NET USE L: \\\\$ARGV[2]\\ADMIN\r\n&quot;;
+               print LOGON &quot;NET USE K: \\\\$ARGV[2]\\MKTING\r\n&quot;;
+       }
+
+       # Now connect Printers.  We handle just two or three users a little
+       # differently, because they are the exceptions that have desktop
+       # printers on LPT1: - all other user's go to the LaserJet on the
+       # server.
+       if ($ARGV[0] eq 'jim'
+           || $ARGV[0] eq 'yvonne')
+       {
+               print LOGON &quot;NET USE LPT2: \\\\$ARGV[2]\\LJET3\r\n&quot;;
+               print LOGON &quot;NET USE LPT3: \\\\$ARGV[2]\\FAXQ\r\n&quot;;
+       }
+       else
+       {
+               print LOGON &quot;NET USE LPT1: \\\\$ARGV[2]\\LJET3\r\n&quot;;
+               print LOGON &quot;NET USE LPT3: \\\\$ARGV[2]\\FAXQ\r\n&quot;;
+       }
+
+       # All done! Close the output file.
+       close LOGON;
+</pre><p>
+</p><p>
+Those wishing to use more elaborate or capable logon processing system should check out the following sites:
+</p><table class="simplelist" border="0" summary="Simple list"><tr><td><a href="http://www.craigelachie.org/rhacer/ntlogon" target="_top">http://www.craigelachie.org/rhacer/ntlogon</a></td></tr><tr><td><a href="http://www.kixtart.org" target="_top">http://www.kixtart.org</a></td></tr><tr><td><a href="http://support.microsoft.com/default.asp?scid=kb;en-us;189105" target="_top">http://support.microsoft.com/default.asp?scid=kb;en-us;189105</a></td></tr></table><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2985283"></a>Adding printers without user intervention</h3></div></div><div></div></div><p>
+Printers may be added automatically during logon script processing through the use of:
+
+</p><pre class="programlisting">
+       rundll32 printui.dll,PrintUIEntry /?
+</pre><p>
+
+See the documentation in the <a href="http://support.microsoft.com/default.asp?scid=kb;en-us;189105" target="_top">Microsoft knowledgebase article no: 189105</a>.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2985316"></a>Common Errors</h2></div></div><div></div></div><p>
+The information provided in this chapter has been reproduced from postings on the samba@samba.org
+mailing list. No implied endorsement or recommendation is offered. Administrators should conduct 
+their own evaluation of alternatives and are encouraged to draw their own conclusions.
+</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="winbind.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="PolicyMgmt.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 21. Integrated Logon Support using Winbind </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 23. System and Account Policies</td></tr></table></div></body></html>

diff --git a/docs/htmldocs/Appendixes.html b/docs/htmldocs/Appendixes.html
new file mode 100644 (file)
index 0000000..854437a
--- /dev/null
+++ b/docs/htmldocs/Appendixes.html
@@ -0,0 +1,4 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Part VI. Appendixes</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="index.html" title="SAMBA Project Documentation"><link rel="previous" href="bugreport.html" title="Chapter 35. Reporting Bugs"><link rel="next" href="compiling.html" title="Chapter 36. How to compile SAMBA"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Part VI. Appendixes</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bugreport.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="compiling.html">Next</a></td></tr></table><hr></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="Appendixes"></a>Appendixes</h1></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>36. <a href="compiling.html">How to compile SAMBA</a></dt><dd><dl><dt><a href="compiling.html#id3012145">Access Samba source code via CVS</a></dt><dd><dl><dt><a href="compiling.html#id3012152">Introduction</a></dt><dt><a href="compiling.html#id3012182">CVS Access to samba.org</a></dt></dl></dd><dt><a href="compiling.html#id3013701">Accessing the samba sources via rsync and ftp</a></dt><dt><a href="compiling.html#id3013750">Verifying Samba's PGP signature</a></dt><dt><a href="compiling.html#id3013886">Building the Binaries</a></dt><dd><dl><dt><a href="compiling.html#id3014023">Compiling samba with Active Directory support</a></dt></dl></dd><dt><a href="compiling.html#id3014188">Starting the smbd and nmbd</a></dt><dd><dl><dt><a href="compiling.html#id3014280">Starting from inetd.conf</a></dt><dt><a href="compiling.html#id3014484">Alternative: starting it as a daemon</a></dt></dl></dd><dt><a href="compiling.html#id3014579">Common Errors</a></dt></dl></dd><dt>37. <a href="Portability.html">Portability</a></dt><dd><dl><dt><a href="Portability.html#id3013478">HPUX</a></dt><dt><a href="Portability.html#id3016009">SCO Unix</a></dt><dt><a href="Portability.html#id3016039">DNIX</a></dt><dt><a href="Portability.html#id3016210">RedHat Linux Rembrandt-II</a></dt><dt><a href="Portability.html#id3016254">AIX</a></dt><dd><dl><dt><a href="Portability.html#id3016261">Sequential Read Ahead</a></dt></dl></dd><dt><a href="Portability.html#id3016287">Solaris</a></dt><dd><dl><dt><a href="Portability.html#id3016294">Locking improvements</a></dt><dt><a href="Portability.html#winbind-solaris9">Winbind on Solaris 9</a></dt></dl></dd></dl></dd><dt>38. <a href="Other-Clients.html">Samba and other CIFS clients</a></dt><dd><dl><dt><a href="Other-Clients.html#id3015663">Macintosh clients?</a></dt><dt><a href="Other-Clients.html#id3017016">OS2 Client</a></dt><dd><dl><dt><a href="Other-Clients.html#id3017023">How can I configure OS/2 Warp Connect or 
+               OS/2 Warp 4 as a client for Samba?</a></dt><dt><a href="Other-Clients.html#id3017102">How can I configure OS/2 Warp 3 (not Connect), 
+               OS/2 1.2, 1.3 or 2.x for Samba?</a></dt><dt><a href="Other-Clients.html#id3017164">How do I get printer driver download working 
+               for OS/2 clients?</a></dt></dl></dd><dt><a href="Other-Clients.html#id3017260">Windows for Workgroups</a></dt><dd><dl><dt><a href="Other-Clients.html#id3017268">Use latest TCP/IP stack from Microsoft</a></dt><dt><a href="Other-Clients.html#id3017357">Delete .pwl files after password change</a></dt><dt><a href="Other-Clients.html#id3017388">Configure WfW password handling</a></dt><dt><a href="Other-Clients.html#id3017433">Case handling of passwords</a></dt><dt><a href="Other-Clients.html#id3017464">Use TCP/IP as default protocol</a></dt><dt><a href="Other-Clients.html#id3017481">Speed improvement</a></dt></dl></dd><dt><a href="Other-Clients.html#id3017528">Windows '95/'98</a></dt><dd><dl><dt><a href="Other-Clients.html#id3017601">Speed improvement</a></dt></dl></dd><dt><a href="Other-Clients.html#id3017625">Windows 2000 Service Pack 2</a></dt><dt><a href="Other-Clients.html#id3017736">Windows NT 3.1</a></dt></dl></dd><dt>39. <a href="speed.html">Samba Performance Tuning</a></dt><dd><dl><dt><a href="speed.html#id3018768">Comparisons</a></dt><dt><a href="speed.html#id3018812">Socket options</a></dt><dt><a href="speed.html#id3018887">Read size</a></dt><dt><a href="speed.html#id3018931">Max xmit</a></dt><dt><a href="speed.html#id3018984">Log level</a></dt><dt><a href="speed.html#id3019007">Read raw</a></dt><dt><a href="speed.html#id3019064">Write raw</a></dt><dt><a href="speed.html#id3019106">Slow Logins</a></dt><dt><a href="speed.html#id3019127">Client tuning</a></dt><dt><a href="speed.html#id3019154">Samba performance problem due changing kernel</a></dt><dt><a href="speed.html#id3019185">Corrupt tdb Files</a></dt></dl></dd><dt>40. <a href="DNSDHCP.html">DNS and DHCP Configuration Guide</a></dt><dd><dl><dt><a href="DNSDHCP.html#id3018605">Note</a></dt></dl></dd><dt>41. <a href="Further-Resources.html">Further Resources</a></dt><dd><dl><dt><a href="Further-Resources.html#id3018765">Websites</a></dt><dt><a href="Further-Resources.html#id3020416">Related updates from Microsoft</a></dt><dt><a href="Further-Resources.html#id3020431">Books</a></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bugreport.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="compiling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 35. Reporting Bugs </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 36. How to compile SAMBA</td></tr></table></div></body></html>

diff --git a/docs/htmldocs/Backup.html b/docs/htmldocs/Backup.html
new file mode 100644 (file)
index 0000000..9fac452
--- /dev/null
+++ b/docs/htmldocs/Backup.html
@@ -0,0 +1,13 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 28. Samba Backup Techniques</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="unicode.html" title="Chapter 27. Unicode/Charsets"><link rel="next" href="SambaHA.html" title="Chapter 29. High Availability Options"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 28. Samba Backup Techniques</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="unicode.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="SambaHA.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Backup"></a>Chapter 28. Samba Backup Techniques</h2></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:jht@samba.org">jht@samba.org</a>&gt;</tt></p></div></div></div></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="Backup.html#id3001533">Note</a></dt><dt><a href="Backup.html#id3001557">Features and Benefits</a></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3001533"></a>Note</h2></div></div><div></div></div><p>
+This chapter did not make it into this release.
+It is planned for the published release of this document.
+If you have something to contribute for this section please email it to
+<a href="">jht@samba.org</a>/
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id3001557"></a>Features and Benefits</h2></div></div><div></div></div><p>
+We need feedback from people who are backing up samba servers.
+We would like to know what software tools you are using to backup
+your samba server/s.
+</p><p>
+In particular, if you have any success and / or failure stories you could
+share with other users this would be appreciated.
+</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unicode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="SambaHA.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 27. Unicode/Charsets </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 29. High Availability Options</td></tr></table></div></body></html>

diff --git a/docs/htmldocs/CUPS-printing.html b/docs/htmldocs/CUPS-printing.html
new file mode 100644 (file)
index 0000000..46ca8e1
--- /dev/null
+++ b/docs/htmldocs/CUPS-printing.html
@@ -0,0 +1,3733 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 19. CUPS Printing Support in Samba 3.0</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="printing.html" title="Chapter 18. Classical Printing Support"><link rel="next" href="VFS.html" title="Chapter 20. Stackable VFS modules"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 19. CUPS Printing Support in Samba 3.0</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="printing.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="VFS.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="CUPS-printing"></a>Chapter 19. CUPS Printing Support in Samba 3.0</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Kurt</span> <span class="surname">Pfeifle</span></h3><div class="affiliation"><span class="orgname"> Danka Deutschland GmbH <br></span><div class="address"><p><tt class="email">&lt;<a href="mailto:kpfeifle@danka.de">kpfeifle@danka.de</a>&gt;</tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Ciprian</span> <span class="surname">Vizitiu</span></h3><span class="contrib">drawings</span><div class="affiliation"><div class="address"><p><tt class="email">&lt;<a href="mailto:CVizitiu@gbif.org">CVizitiu@gbif.org</a>&gt;</tt></p></div></div></div></div><div><p class="pubdate"> (3 June 2003) </p></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="CUPS-printing.html#id2953785">Introduction</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2953792">Features and Benefits</a></dt><dt><a href="CUPS-printing.html#id2953845">Overview</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2953900">Basic Configuration of CUPS support</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2953979">Linking of smbd with libcups.so</a></dt><dt><a href="CUPS-printing.html#id2954122">Simple smb.conf Settings for CUPS</a></dt><dt><a href="CUPS-printing.html#id2954205">More complex smb.conf Settings for
+CUPS</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2954322">Advanced Configuration</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2954343">Central spooling vs. &quot;Peer-to-Peer&quot; printing</a></dt><dt><a href="CUPS-printing.html#id2954370">CUPS/Samba as a &quot;spooling-only&quot; Print Server; &quot;raw&quot; printing
+with Vendor Drivers on Windows Clients</a></dt><dt><a href="CUPS-printing.html#id2954406">Driver Installation Methods on Windows Clients</a></dt><dt><a href="CUPS-printing.html#id2954465">Explicitly enable &quot;raw&quot; printing for
+application/octet-stream!</a></dt><dt><a href="CUPS-printing.html#id2954626">Three familiar Methods for driver upload plus a new one</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2954719">Using CUPS/Samba in an advanced Way -- intelligent printing
+with PostScript Driver Download</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2954794">GDI on Windows -- PostScript on Unix</a></dt><dt><a href="CUPS-printing.html#id2954839">Windows Drivers, GDI and EMF</a></dt><dt><a href="CUPS-printing.html#id2954940">Unix Printfile Conversion and GUI Basics</a></dt><dt><a href="CUPS-printing.html#id2955028">PostScript and Ghostscript</a></dt><dt><a href="CUPS-printing.html#id2955125">Ghostscript -- the Software RIP for non-PostScript Printers</a></dt><dt><a href="CUPS-printing.html#id2955238">PostScript Printer Description (PPD) Specification</a></dt><dt><a href="CUPS-printing.html#id2955308">CUPS can use all Windows-formatted Vendor PPDs</a></dt><dt><a href="CUPS-printing.html#id2955397">CUPS also uses PPDs for non-PostScript Printers</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2955420">The CUPS Filtering Architecture</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2955560">MIME types and CUPS Filters</a></dt><dt><a href="CUPS-printing.html#id2955747">MIME type Conversion Rules</a></dt><dt><a href="CUPS-printing.html#id2955864">Filter Requirements</a></dt><dt><a href="CUPS-printing.html#id2956034">Prefilters</a></dt><dt><a href="CUPS-printing.html#id2956120">pstops</a></dt><dt><a href="CUPS-printing.html#id2956222">pstoraster</a></dt><dt><a href="CUPS-printing.html#id2956377">imagetops and imagetoraster</a></dt><dt><a href="CUPS-printing.html#id2956434">rasterto [printers specific]</a></dt><dt><a href="CUPS-printing.html#id2956519">CUPS Backends</a></dt><dt><a href="CUPS-printing.html#id2956831">cupsomatic/Foomatic -- how do they fit into the Picture?</a></dt><dt><a href="CUPS-printing.html#id2956944">The Complete Picture</a></dt><dt><a href="CUPS-printing.html#id2956960">mime.convs</a></dt><dt><a href="CUPS-printing.html#id2957012">&quot;Raw&quot; printing</a></dt><dt><a href="CUPS-printing.html#id2957066">&quot;application/octet-stream&quot; printing</a></dt><dt><a href="CUPS-printing.html#id2957282">PostScript Printer Descriptions (PPDs) for non-PS Printers</a></dt><dt><a href="CUPS-printing.html#id2957510">Difference between cupsomatic/foomatic-rip and
+native CUPS printing</a></dt><dt><a href="CUPS-printing.html#id2957666">Examples for filtering Chains</a></dt><dt><a href="CUPS-printing.html#id2957897">Sources of CUPS drivers / PPDs</a></dt><dt><a href="CUPS-printing.html#id2958024">Printing with Interface Scripts</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2958100">Network printing (purely Windows)</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2958116">From Windows Clients to an NT Print Server</a></dt><dt><a href="CUPS-printing.html#id2958155">Driver Execution on the Client</a></dt><dt><a href="CUPS-printing.html#id2958227">Driver Execution on the Server</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2958289">Network Printing (Windows clients -- UNIX/Samba Print
+Servers)</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2958310">From Windows Clients to a CUPS/Samba Print Server</a></dt><dt><a href="CUPS-printing.html#id2958474">Samba receiving Jobfiles and passing them to CUPS</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2958550">Network PostScript RIP: CUPS Filters on Server -- clients use
+PostScript Driver with CUPS-PPDs</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2958605">PPDs for non-PS Printers on UNIX</a></dt><dt><a href="CUPS-printing.html#id2958646">PPDs for non-PS Printers on Windows</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2958712">Windows Terminal Servers (WTS) as CUPS Clients</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2958729">Printer Drivers running in &quot;Kernel Mode&quot; cause many
+Problems</a></dt><dt><a href="CUPS-printing.html#id2958763">Workarounds impose Heavy Limitations</a></dt><dt><a href="CUPS-printing.html#id2958784">CUPS: a &quot;Magical Stone&quot;?</a></dt><dt><a href="CUPS-printing.html#id2958811">PostScript Drivers with no major problems -- even in Kernel
+Mode</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2958865"> Setting up CUPS for driver Download</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2958884">cupsaddsmb: the unknown Utility</a></dt><dt><a href="CUPS-printing.html#id2958976">Prepare your smb.conf for
+cupsaddsmb</a></dt><dt><a href="CUPS-printing.html#id2959022">CUPS Package of &quot;PostScript Driver for WinNT/2k/XP&quot;</a></dt><dt><a href="CUPS-printing.html#id2959220">Recognize the different Driver Files</a></dt><dt><a href="CUPS-printing.html#id2959278">Acquiring the Adobe Driver Files</a></dt><dt><a href="CUPS-printing.html#id2959310">ESP Print Pro Package of &quot;PostScript Driver for
+WinNT/2k/XP&quot;</a></dt><dt><a href="CUPS-printing.html#id2959360">Caveats to be considered</a></dt><dt><a href="CUPS-printing.html#id2959582">What are the Benefits of using the &quot;CUPS PostScript Driver for
+Windows NT/2k/XP&quot; as compared to the Adobe Driver?</a></dt><dt><a href="CUPS-printing.html#id2959764">Run &quot;cupsaddsmb&quot; (quiet Mode)</a></dt><dt><a href="CUPS-printing.html#id2959865">Run &quot;cupsaddsmb&quot; with verbose Output</a></dt><dt><a href="CUPS-printing.html#id2960092">Understanding cupsaddsmb</a></dt><dt><a href="CUPS-printing.html#id2960186">How to recognize if cupsaddsm completed successfully</a></dt><dt><a href="CUPS-printing.html#id2960273">cupsaddsmb with a Samba PDC</a></dt><dt><a href="CUPS-printing.html#id2960308">cupsaddsmb Flowchart</a></dt><dt><a href="CUPS-printing.html#id2960361">Installing the PostScript Driver on a Client</a></dt><dt><a href="CUPS-printing.html#id2960474">Avoiding critical PostScript Driver Settings on the
+Client</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2960608">Installing PostScript Driver Files manually (using
+rpcclient)</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2960723">A Check of the rpcclient man Page</a></dt><dt><a href="CUPS-printing.html#id2960836">Understanding the rpcclient man Page</a></dt><dt><a href="CUPS-printing.html#id2960925">Producing an Example by querying a Windows Box</a></dt><dt><a href="CUPS-printing.html#id2961015">What is required for adddriver and setdriver to succeed</a></dt><dt><a href="CUPS-printing.html#id2961177">Manual Commandline Driver Installation in 15 little Steps</a></dt><dt><a href="CUPS-printing.html#id2961830">Troubleshooting revisited</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2961930">The printing *.tdb Files</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2962033">Trivial DataBase Files</a></dt><dt><a href="CUPS-printing.html#id2962103">Binary Format</a></dt><dt><a href="CUPS-printing.html#id2962165">Losing *.tdb Files</a></dt><dt><a href="CUPS-printing.html#id2962224">Using tdbbackup</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2962290">CUPS Print Drivers from Linuxprinting.org</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2962398">foomatic-rip and Foomatic explained</a></dt><dt><a href="CUPS-printing.html#id2963027">foomatic-rip and Foomatic-PPD Download and Installation</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2963488">Page Accounting with CUPS</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2963519">Setting up Quotas</a></dt><dt><a href="CUPS-printing.html#id2963551">Correct and incorrect Accounting</a></dt><dt><a href="CUPS-printing.html#id2963592">Adobe and CUPS PostScript Drivers for Windows Clients</a></dt><dt><a href="CUPS-printing.html#id2963663">The page_log File Syntax</a></dt><dt><a href="CUPS-printing.html#id2963765">Possible Shortcomings</a></dt><dt><a href="CUPS-printing.html#id2963836">Future Developments</a></dt><dt><a href="CUPS-printing.html#id2963884">Other Accounting Tools</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2963899">Additional Material</a></dt><dt><a href="CUPS-printing.html#id2964092">Auto-Deletion or Preservation of CUPS Spool Files</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2964138">CUPS Configuration Settings explained</a></dt><dt><a href="CUPS-printing.html#id2964221">Pre-conditions</a></dt><dt><a href="CUPS-printing.html#id2964281">Manual Configuration</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2964299">When not to use Samba to print to
+CUPS</a></dt><dt><a href="CUPS-printing.html#id2964316">In Case of Trouble.....</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2964352">Where to find Documentation</a></dt><dt><a href="CUPS-printing.html#id2964364">How to ask for Help</a></dt><dt><a href="CUPS-printing.html#id2964377">Where to find Help</a></dt></dl></dd><dt><a href="CUPS-printing.html#id2964391">Appendix</a></dt><dd><dl><dt><a href="CUPS-printing.html#id2964398">Printing from CUPS to Windows attached
+Printers</a></dt><dt><a href="CUPS-printing.html#id2964612">More CUPS filtering Chains</a></dt><dt><a href="CUPS-printing.html#id2964919">Trouble Shooting Guidelines to fix typical Samba printing
+Problems</a></dt><dt><a href="CUPS-printing.html#id2966041">An Overview of the CUPS Printing Processes</a></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2953785"></a>Introduction</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2953792"></a>Features and Benefits</h3></div></div><div></div></div><p>
+                       The Common Unix Print System (<a href="http://www.cups.org/" target="_top">CUPS</a>) has become very popular. All
+                       big Linux distributions now ship it as their default printing
+                       system. But to many it is still a very mystical tool.  Normally it
+                       &quot;just works&quot; (TM). People tend to regard it as a sort of &quot;black box&quot;,
+                       which they don't want to look into, as long as it works OK. But once
+                       there is a little problem, they are in trouble to find out where to
+                       start debugging it. Also, even the most recent and otherwise excellent
+                       printed Samba documentation has only limited attention paid to CUPS
+                       printing, leaving out important pieces or even writing plain wrong
+                       things about it. This demands rectification.  But before you dive into
+                       this chapter, make sure that you don't forget to refer to the
+                       &quot;Classical Printing&quot; chapter also. It contains a lot of information
+                       that is relevant for CUPS too.
+               </p><p>
+                       CUPS sports quite a few unique and powerful features. While their
+                       basic functions may be grasped quite easily, they are also
+                       new. Because they are different from other, more traditional printing
+                       systems, it is best to try and not apply any prior knowledge about
+                       printing upon this new system. Rather try to start understand CUPS
+                       from the beginning. This documentation will lead you here to a
+                       complete understanding of CUPS, if you study all of the material
+                       contained. But lets start with the most basic things first. Maybe this
+                       is all you need for now. Then you can skip most of the other
+                       paragraphs.
+               </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2953845"></a>Overview</h3></div></div><div></div></div><p>
+                       CUPS is more than just a print spooling system. It is a complete
+                       printer management system that complies with the new IPP
+                       (<span class="emphasis"><em>Internet Printing Protocol</em></span>). IPP is an industry
+                       and IETF (<span class="emphasis"><em>Internet Engineering Task Force</em></span>)
+                       standard for network printing. Many of its functions can be managed
+                       remotely (or locally) via a web browser (giving you a
+                       platform-independent access to the CUPS print server). In addition it
+                       has the traditional commandline and several more modern GUI interfaces
+                       (GUI interfaces developed by 3rd parties, like KDE's
+                       overwhelming <a href="http://printing.kde.org/" target="_top">KDEPrint</a>).
+               </p><p>
+                       CUPS allows creation of &quot;raw&quot; printers (ie: NO print file
+                       format translation) as well as &quot;smart&quot; printers (i.e. 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
+                       argue 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.
+               </p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2953900"></a>Basic Configuration of CUPS support</h2></div></div><div></div></div><p>
+               Printing with CUPS in the most basic <tt class="filename">smb.conf</tt>
+               setup in Samba 3.0 (as was true for 2.2.x) only needs two
+               settings: <i class="parameter"><tt>printing = cups</tt></i> and <i class="parameter"><tt>printcap
+                       = cups</tt></i>. CUPS itself doesn't need a printcap file
+               anymore. However, the <tt class="filename">cupsd.conf</tt> configuration
+               file knows two related directives: they control if such a file should
+               be automatically created and maintained by CUPS for the convenience of
+               third party applications (example: <i class="parameter"><tt>Printcap
+                       /etc/printcap</tt></i> and <i class="parameter"><tt>PrintcapFormat
+                       BSD</tt></i>). These legacy programs often require the existence of
+               printcap file containing printernames or they will refuse to
+               print. Make sure CUPS is set to generate and maintain a printcap! For
+               details see <b class="command">man cupsd.conf</b> and other CUPS-related
+               documentation, like the wealth of documents on your CUPS server
+               itself: <a href="http://localhost:631/documentation.html" target="_top">http://localhost:631/documentation.html</a>.
+       </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2953979"></a>Linking of smbd with libcups.so</h3></div></div><div></div></div><p>
+                       Samba has a very special relationship to CUPS. The reason is: Samba
+                       can be compiled with CUPS library support. Most recent installations
+                       have this support enabled, and per default CUPS linking is compiled
+                       into smbd and other Samba binaries. Of course, you can use CUPS even
+                       if Samba is not linked against <tt class="filename">libcups.so</tt> -- but
+                       there are some differences in required or supported configuration
+                       then.
+               </p><p>
+                       If SAMBA is compiled against libcups, then <i class="parameter"><tt>printcap =
+                               cups</tt></i> uses the CUPS API to list printers, submit jobs,
+                       query queues, etc.  Otherwise it maps to the System V commands with an
+                       additional <b class="command">-oraw</b> option for printing. On a Linux
+                       system, you can use the <b class="command">ldd</b> utility to find out
+                       details (ldd may not be present on other OS platforms, or its function
+                       may be embodied by a different command):
+               </p><pre class="screen">
+                               transmeta:/home/kurt # ldd `which smbd`
+                               libssl.so.0.9.6 =&gt; /usr/lib/libssl.so.0.9.6 (0x4002d000)
+                               libcrypto.so.0.9.6 =&gt; /usr/lib/libcrypto.so.0.9.6 (0x4005a000)
+                               libcups.so.2 =&gt; /usr/lib/libcups.so.2 (0x40123000)
+                               [....]
+               </pre><p>
+                       The line <tt class="computeroutput">libcups.so.2 =&gt; /usr/lib/libcups.so.2
+                               (0x40123000)</tt> shows there is CUPS support compiled
+                       into this version of Samba. If this is the case, and printing = cups
+                       is set, then <span class="emphasis"><em>any otherwise manually set print command in
+                               <tt class="filename">smb.conf</tt> is ignored</em></span>. This is an
+                       important point to remember!
+               </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p> Should you require -- for any reason -- to set your own
+                               print commands, you can still do this by setting <i class="parameter"><tt>printing =
+                                       sysv</tt></i>. However, you'll loose all the benefits from the
+                               close CUPS/Samba integration. You are on your own then to manually
+                               configure the rest of the printing system commands (most important:
+                               <i class="parameter"><tt>print command</tt></i>; other commands are
+                               <i class="parameter"><tt>lppause command, lpresume command, lpq command, lprm
+                                       command, queuepause command </tt></i> and <i class="parameter"><tt>queue resume
+                                       command</tt></i>).</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954122"></a>Simple <tt class="filename">smb.conf</tt> Settings for CUPS</h3></div></div><div></div></div><p>
+                       To summarize, here is the simplest printing-related setup
+                       for <tt class="filename">smb.conf</tt> to enable basic CUPS support:
+               </p><pre class="screen">
+
+                               [global]
+                               load printers = yes
+                               printing = cups
+                               printcap name = cups
+
+                               [printers]
+                               comment = All Printers
+                               path = /var/spool/samba
+                               browseable = no
+                               public = yes
+                               guest ok = yes
+                               writable = no
+                               printable = yes
+                               printer admin = root, @ntadmins
+
+               </pre><p>
+                       This is all you need for basic printing setup for CUPS. It will print
+                       all Graphic, Text, PDF and PostScript file submitted from Windows
+                       clients. However, most of your Windows users would not know how to
+                       send these kind of files to print without opening a GUI
+                       application. Windows clients tend to have local printer drivers
+                       installed. And the GUI application's print buttons start a printer
+                       driver. Your users also very rarely send files from the command
+                       line. Unlike UNIX clients, they hardly submit graphic, text or PDF
+                       formatted files directly to the spooler. They nearly exclusively print
+                       from GUI applications, with a &quot;printer driver&quot; hooked in between the
+                       applications native format and the print data stream.  If the backend
+                       printer is not a PostScript device, the print data stream is &quot;binary&quot;,
+                       sensible only for the target printer. Read on to learn which problem
+                       this may cause and how to avoid it.
+               </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954205"></a>More complex <tt class="filename">smb.conf</tt> Settings for
+CUPS</h3></div></div><div></div></div><p>
+Here is a slightly more complex printing-related setup
+for <tt class="filename">smb.conf</tt>. It enables general CUPS printing
+support for all printers, but defines one printer share which is set
+up differently.
+</p><pre class="screen">
+
+ [global]
+         printing = cups
+         printcap name = cups
+         load printers = yes
+
+ [printers]
+         comment = All Printers
+         path = /var/spool/samba
+         public = yes
+         guest ok = yes
+         writable = no
+         printable = yes
+         printer admin = root, @ntadmins
+ 
+ [special_printer]
+         comment = A special printer with his own settings
+         path = /var/spool/samba-special
+         printing = sysv
+         printcap = lpstat
+         print command = echo &quot;NEW: `date`: printfile %f&quot; &gt;&gt; /tmp/smbprn.log ;\
+                         echo &quot;     `date`: p-%p s-%s f-%f&quot; &gt;&gt; /tmp/smbprn.log ;\
+                         echo &quot;     `date`: j-%j J-%J z-%z c-%c&quot; &gt;&gt; /tmp/smbprn.log :\
+                         rm %f
+         public = no
+         guest ok = no
+         writeable = no
+         printable = yes
+         printer admin = kurt
+         hosts deny = 0.0.0.0
+         hosts allow = turbo_xp, 10.160.50.23, 10.160.51.60
+
+</pre><p>
+This special share is only there for my testing purposes. It doesn't
+even write the print job to a file. It just logs the job parameters
+known to Samba into the <tt class="filename">/tmp/smbprn.log</tt> file and
+deletes the jobfile. Moreover, the <i class="parameter"><tt>printer
+admin</tt></i> of this share is &quot;kurt&quot; (not the &quot;@ntadmins&quot; group);
+guest access is not allowed; the share isn't announced in Network
+Neighbourhood (so you need to know it is there), and it is only
+allowing access from three hosts. To prevent CUPS kicking in and
+taking over the print jobs for that share, we need to set
+<i class="parameter"><tt>printing = sysv</tt></i> and <i class="parameter"><tt>printcap =
+lpstat</tt></i>.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2954322"></a>Advanced Configuration</h2></div></div><div></div></div><p>
+Before we dive into all the configuration options, let's clarify a few
+points. <span class="emphasis"><em>Network printing needs to be organized and setup
+correctly</em></span>. Often this is not done correctly. Legacy systems
+or small LANs in business environments often lack a clear design and
+good housekeeping.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954343"></a>Central spooling vs. &quot;Peer-to-Peer&quot; printing</h3></div></div><div></div></div><p>
+Many small office or home networks, as well as badly organized larger
+environments, allow each client a direct access to available network
+printers. Generally, this is a bad idea. It often blocks one client's
+access to the printer when another client's job is printing. It also
+might freeze the first client's application while it is waiting to get
+rid of the job. Also, there are frequent complaints about various jobs
+being printed with their pages mixed with each other. A better concept
+is the usage of a &quot;print server&quot;: it routes all jobs through one
+central system, which responds immediately, takes jobs from multiple
+concurrent clients at the same time and in turn transfers them to the
+printer(s) in the correct order.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954370"></a>CUPS/Samba as a &quot;spooling-only&quot; Print Server; &quot;raw&quot; printing
+with Vendor Drivers on Windows Clients</h3></div></div><div></div></div><p>
+Most traditionally configured Unix print servers acting on behalf of
+Samba's Windows clients represented a really simple setup. Their only
+task was to manage the &quot;raw&quot; spooling of all jobs handed to them by
+Samba. This approach meant that the Windows clients were expected to
+prepare the print job file in such a way that it became fit to be fed to
+the printing device. Here a native (vendor-supplied) Windows printer
+driver for the target device needed to be installed on each and every
+client.
+</p><p>
+Of course you can setup CUPS, Samba and your Windows clients in the
+same, traditional and simple way. 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). The file must be
+sent in a format that is suitable for direct delivery to the
+printer. Clients need to run the vendor-provided drivers to do
+this. In this case CUPS will NOT do any print file format conversion
+work.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954406"></a>Driver Installation Methods on Windows Clients</h3></div></div><div></div></div><p>
+The printer drivers on the Windows clients may be installed
+in two functionally different ways:
+</p><div class="itemizedlist"><ul type="disc"><li><p>manually install the drivers locally on each client,
+one by one; this yields the old <span class="emphasis"><em>LanMan</em></span> style
+printing; it uses a <tt class="filename">\\sambaserver\printershare</tt>
+type of connection.</p></li><li><p>deposit and prepare the drivers (for later download) on
+the print server (Samba); this enables the clients to use
+&quot;Point'n'Print&quot; to get drivers semi-automatically installed the
+first time they access the printer; with this method NT/2K/XP
+clients use the <span class="emphasis"><em>SPOOLSS/MS-RPC</em></span>
+type printing calls.</p></li></ul></div><p>
+The second method is recommended for use over the first.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954465"></a>Explicitly enable &quot;raw&quot; printing for
+<span class="emphasis"><em>application/octet-stream</em></span>!</h3></div></div><div></div></div><p>
+If you use the first option (drivers are installed on the client
+side), there is one setting to take care of: CUPS needs to be told
+that it should allow &quot;raw&quot; printing of deliberate (binary) file
+formats. The CUPS files that need to be correctly set for RAW mode
+printers to work are:
+</p><div class="itemizedlist"><ul type="disc"><li><p>/etc/cups/mime.types
+</p></li><li><p>/etc/cups/mime.convs</p></li></ul></div><p>
+Both contain entries (at the end of the respective files) which must
+be uncommented to allow RAW mode operation.
+In<tt class="filename">/etc/cups/mime.types</tt> make sure this line is
+present:
+</p><pre class="screen">
+
+ application/octet-stream
+
+</pre><p>
+In <tt class="filename">/etc/cups/mime.convs</tt>,
+have this line:
+</p><pre class="screen">
+
+ application/octet-stream   application/vnd.cups-raw   0   - 
+
+</pre><p>
+If these two files are not set up correctly for raw Windows client
+printing, you may encounter the dreaded <tt class="computeroutput">Unable to
+convert file 0</tt> in your CUPS error_log file. 
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>editing the <tt class="filename">mime.convs</tt> and the
+<tt class="filename">mime.types</tt> file does not
+<span class="emphasis"><em>enforce</em></span> &quot;raw&quot; printing, it only
+<span class="emphasis"><em>allows</em></span> it.
+</p></div><p><b>Background. </b>
+CUPS being a more security-aware printing system than traditional ones
+does not by default allow a user to send deliberate (possibly binary)
+data to printing devices. This could be easily abused to launch a
+&quot;Denial of Service&quot; attack on your printer(s), causing at the least
+the loss of a lot of paper and ink. &quot;Unknown&quot; data are tagged by CUPS
+as <span class="emphasis"><em>MIME type: application/octet-stream</em></span> and not
+allowed to go to the printer. By default, you can only send other
+(known) MIME types &quot;raw&quot;. Sending data &quot;raw&quot; means that CUPS does not
+try to convert them and passes them to the printer untouched (see next
+chapter for even more background explanations).
+</p><p>
+This is all you need to know to get the CUPS/Samba combo printing
+&quot;raw&quot; files prepared by Windows clients, which have vendor drivers
+locally installed. If you are not interested in background information about
+more advanced CUPS/Samba printing, simply skip the remaining sections
+of this chapter.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954626"></a>Three familiar Methods for driver upload plus a new one</h3></div></div><div></div></div><p>
+If you want to use the MS-RPC type printing, you must upload the
+drivers onto the Samba server first (<i class="parameter"><tt>[print$]</tt></i>
+share). For a discussion on how to deposit printer drivers on the
+Samba host (so that the Windows clients can download and use them via
+&quot;Point'n'Print&quot;) please also refer to the previous chapter of this
+HOWTO Collection. There you will find a description or reference to
+three methods of preparing the client drivers on the Samba server:
+</p><div class="itemizedlist"><ul type="disc"><li><p>the GUI, &quot;Add Printer Wizard&quot;
+<span class="emphasis"><em>upload-from-a-Windows-client</em></span>
+method;</p></li><li><p>the commandline, &quot;smbclient/rpcclient&quot;
+<span class="emphasis"><em>upload-from-a-UNIX-workstation</em></span>
+method;</p></li><li><p>the <span class="emphasis"><em>Imprints</em></span> Toolset
+method.</p></li></ul></div><p>
+These 3 methods apply to CUPS all the same. A new and more
+convenient way to load the Windows drivers into Samba is provided
+provided if you use CUPS:
+</p><div class="itemizedlist"><ul type="disc"><li><p>the <span class="emphasis"><em>cupsaddsmb</em></span>
+utility.</p></li></ul></div><p>
+cupsaddsmb is discussed in much detail further below. But we will
+first explore the CUPS filtering system and compare the Windows and
+UNIX printing architectures.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2954719"></a>Using CUPS/Samba in an advanced Way -- intelligent printing
+with PostScript Driver Download</h2></div></div><div></div></div><p>
+Still reading on? Good. Let's go into more detail then. We now know
+how to set up a &quot;dump&quot; printserver, that is, a server which is spooling
+printjobs &quot;raw&quot;, leaving the print data untouched.
+</p><p>
+Possibly you need to setup CUPS in a more smart way. The reasons could
+be manifold:
+</p><div class="itemizedlist"><ul type="disc"><li><p>Maybe your boss wants to get monthly statistics: Which
+printer did how many pages? What was the average data size of a job?
+What was the average print run per day? What are the typical hourly
+peaks in printing? Which departments prints how
+much?</p></li><li><p>Maybe you are asked to setup a print quota system:
+users should not be able to print more jobs, once they have surpassed
+a given limit per period?</p></li><li><p>Maybe your previous network printing setup is a mess
+and shall be re-organized from a clean beginning?</p></li><li><p>Maybe you have experiencing too many &quot;Blue Screens&quot;,
+originating from poorly debugged printer drivers running in NT &quot;kernel
+mode&quot;?</p></li></ul></div><p>
+These goals cannot be achieved by a raw print server. To build a
+server meeting these requirements, you'll first need to learn about
+how CUPS works and how you can enable its features.
+</p><p>
+What follows is the comparison of some fundamental concepts for
+Windows and Unix printing; then is the time for a description of the
+CUPS filtering system, how it works and how you can tweak it.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954794"></a>GDI on Windows -- PostScript on Unix</h3></div></div><div></div></div><p>
+Network printing is one of the most complicated and error-prone
+day-to-day tasks any user or an administrator may encounter. This is
+true for all OS platforms. And there are reasons for this.
+</p><p>
+You can't expect for most file formats to just throw them towards
+printers and they get printed. There needs to be a file format
+conversion in between. The problem is: there is no common standard for
+print file formats across all manufacturers and printer types.  While
+<span class="emphasis"><em>PostScript</em></span> (trademark held by Adobe), and, to an
+extent, <span class="emphasis"><em>PCL</em></span> (trademark held by HP), have developed
+into semi-official &quot;standards&quot;, by being the most widely used PDLs
+(<span class="emphasis"><em>Page Description Languages</em></span>), there are still
+many manufacturers who &quot;roll their own&quot; (their reasons may be
+unacceptable license fees for using printer-embedded PostScript
+interpreters, etc.).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954839"></a>Windows Drivers, GDI and EMF</h3></div></div><div></div></div><p>
+In Windows OS, the format conversion job is done by the printer
+drivers. On MS Windows OS platforms all application programmers have
+at their disposal a built-in API, the GDI (<span class="emphasis"><em>Graphical Device
+Interface</em></span>), as part and parcel of the OS itself, to base
+themselves on. This GDI core is used as one common unified ground, for
+all Windows programs, to draw pictures, fonts and documents
+<span class="emphasis"><em>on screen</em></span> as well as <span class="emphasis"><em>on
+paper</em></span> (=print). Therefore printer driver developers can
+standardize on a well-defined GDI output for their own driver
+input. Achieving WYSIWYG (&quot;What You See Is What You Get&quot;) is
+relatively easy, because the on-screen graphic primitives, as well as
+the on-paper drawn objects, come from one common source. This source,
+the GDI, produces often a file format called EMF (<span class="emphasis"><em>Enhanced
+MetaFile</em></span>). The EMF is processed by the printer driver and
+converted to the printer-specific file format.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+To the GDI foundation in MS Windows, Apple has chosen to
+put paper and screen output on a common foundation for their
+(BSD-Unix-based, did you know??) Mac OS X and Darwin Operating
+Systems.Their <span class="emphasis"><em>Core Graphic Engine</em></span> uses a
+<span class="emphasis"><em>PDF</em></span> derivate for all display work.
+</p></div><p>
+
+</p><div class="figure"><a name="id2954904"></a><p class="title"><b>Figure 19.1. Windows Printing to a local Printer</b></p><div class="mediaobject"><img src="projdoc/imagefiles/1small.png" alt="Windows Printing to a local Printer"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2954940"></a>Unix Printfile Conversion and GUI Basics</h3></div></div><div></div></div><p>
+In Unix and Linux, there is no comparable layer built into the OS
+kernel(s) or the X (screen display) server. Every application is
+responsible for itself to create its print output.  Fortunately, most
+use PostScript. That gives at least some common ground. Unfortunately,
+there are many different levels of quality for this PostScript. And
+worse: there is a huge difference (and no common root) in the way how
+the same document is displayed on screen and how it is presented on
+paper. WYSIWYG is more difficult to achieve. This goes back to the
+time decades ago, when the predecessors of <span class="emphasis"><em>X.org</em></span>,
+designing the UNIX foundations and protocols for Graphical User
+Interfaces refused to take over responsibility for &quot;paper output&quot;
+also, as some had demanded at the time, and restricted itself to
+&quot;on-screen only&quot;.  (For some years now, the &quot;Xprint&quot; project has been
+under development, attempting to build printing support into the X
+framework, including a PostScript and a PCL driver, but it is not yet
+ready for prime time.) You can see this unfavorable inheritance up to
+the present day by looking into the various &quot;font&quot; directories on your
+system; there are separate ones for fonts used for X display and fonts
+to be used on paper.
+</p><p><b>Background. </b>
+The PostScript programming language is an &quot;invention&quot; by Adobe Inc.,
+but its specifications have been published to the full. Its strength
+lies in its powerful abilities to describe graphical objects (fonts,
+shapes, patterns, lines, curves, dots...), their attributes (color,
+linewidth...) and the way to manipulate (scale, distort, rotate,
+shift...) them.  Because of its open specification, anybody with the
+skill can start writing his own implementation of a PostScript
+interpreter and use it to display PostScript files on screen or on
+paper. Most graphical output devices are based on the concept of
+&quot;raster images&quot; or &quot;pixels&quot; (one notable exception are pen
+plotters). Of course, you can look at a PostScript file in its textual
+form and you will be reading its PostScript code, the language
+instructions which need to be interpreted by a rasterizer. Rasterizers
+produce pixel images, which may be displayed on screen by a viewer
+program or on paper by a printer.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955028"></a>PostScript and Ghostscript</h3></div></div><div></div></div><p>
+So, Unix is lacking a common ground for printing on paper and
+displaying on screen. Despite this unfavorable legacy for Unix, basic
+printing is fairly easy: if you have PostScript printers at your
+disposal! The reason is: these devices have a built-in PostScript
+language &quot;interpreter&quot;, also called a <span class="emphasis"><em>Raster Image
+Processor</em></span> (RIP), (which makes them more expensive than
+other types of printers); throw PostScript towards them, and they will
+spit out your printed pages. Their RIP is doing all the hard work of
+converting the PostScript drawing commands into a bitmap picture as
+you see it on paper, in a resolution as done by your printer. This is
+no different to PostScript printing of a file from a Windows origin.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Traditional Unix programs and printing systems -- while
+using PostScript -- are largely not PPD-aware. PPDs are &quot;PostScript
+Printer Description&quot; files. They enable you to specify and control all
+options a printer supports: duplexing, stapling, punching... Therefore
+Unix users for a long time couldn't choose many of the supported
+device and job options, unlike Windows or Apple users. But now there
+is CUPS.... ;-)
+</p></div><p>
+</p><div class="figure"><a name="id2955075"></a><p class="title"><b>Figure 19.2. Printing to a Postscript Printer</b></p><div class="mediaobject"><img src="projdoc/imagefiles/2small.png" alt="Printing to a Postscript Printer"></div></div><p>
+</p><p>
+However, there are other types of printers out there. These don't know
+how to print PostScript. They use their own <span class="emphasis"><em>Page Description
+Language</em></span> (PDL, often proprietary). To print to them is much
+more demanding. Since your Unix applications mostly produce
+PostScript, and since these devices don't understand PostScript, you
+need to convert the printfiles to a format suitable for your printer
+on the host, before you can send it away.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955125"></a>Ghostscript -- the Software RIP for non-PostScript Printers</h3></div></div><div></div></div><p>
+Here is where <span class="emphasis"><em>Ghostscript</em></span> kicks in. Ghostscript is
+the traditional (and quite powerful) PostScript interpreter used on
+Unix platforms. It is a RIP in software, capable to do a
+<span class="emphasis"><em>lot</em></span> of file format conversions, for a very broad
+spectrum of hardware devices as well as software file formats.
+Ghostscript technology and drivers is what enables PostScript printing
+to non-PostScript hardware.
+</p><p>
+</p><div class="figure"><a name="id2955155"></a><p class="title"><b>Figure 19.3. Ghostscript as a RIP for non-postscript printers</b></p><div class="mediaobject"><img src="projdoc/imagefiles/3small.png" alt="Ghostscript as a RIP for non-postscript printers"></div></div><p>
+</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+Use the &quot;gs -h&quot; command to check for all built-in &quot;devices&quot; of your
+Ghostscript version. If you specify e.g. a parameter of
+<i class="parameter"><tt>-sDEVICE=png256</tt></i> on your Ghostscript command
+line, you are asking Ghostscript to convert the input into a PNG
+file. Naming a &quot;device&quot; on the commandline is the most important
+single parameter to tell Ghostscript how exactly it should render the
+input. New Ghostscript versions are released at fairly regular
+intervals, now by artofcode LLC. They are initially put under the
+&quot;AFPL&quot; license, but re-released under the GNU GPL as soon as the next
+AFPL version appears. GNU Ghostscript is probably the version
+installed on most Samba systems. But it has got some
+deficiencies. Therefore ESP Ghostscript was developed as an
+enhancement over GNU Ghostscript, with lots of bug-fixes, additional
+devices and improvements. It is jointly maintained by developers from
+CUPS, Gimp-Print, MandrakeSoft, SuSE, RedHat and Debian. It includes
+the &quot;cups&quot; device (essential to print to non-PS printers from CUPS).
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955238"></a>PostScript Printer Description (PPD) Specification</h3></div></div><div></div></div><p>
+While PostScript in essence is a <span class="emphasis"><em>Page Description
+Language</em></span> (PDL) to represent the page layout in a
+<span class="emphasis"><em>device independent</em></span> way, real world print jobs are
+always ending up to be output on a hardware with device-specific
+features. To take care of all the differences in hardware, and to
+allow for innovations, Adobe has specified a syntax and file format
+for <span class="emphasis"><em>PostScript Printer Description</em></span> (PPD)
+files. Every PostScript printer ships with one of these files.
+</p><p>
+PPDs contain all information about general and special features of the
+given printer model: Which different resolutions can it handle? Does
+it have a Duplexing Unit? How many paper trays are there? What media
+types and sizes does it take? For each item it also names the special
+command string to be sent to the printer (mostly inside the PostScript
+file) in order to enable it.
+</p><p>
+Information from these PPDs is meant to be taken into account by the
+printer drivers. Therefore, installed as part of the Windows
+PostScript driver for a given printer is the printer's PPD. Where it
+makes sense, the PPD features are presented in the drivers' UI dialogs
+to display to the user as choice of print options. In the end, the
+user selections are somehow written (in the form of special
+PostScript, PJL, JCL or vendor-dependent commands) into the PostScript
+file created by the driver.
+</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+A PostScript file that was created to contain device-specific commands
+for achieving a certain print job output (e.g. duplexed, stapled and
+punched) on a specific target machine, may not print as expected, or
+may not be printable at all on other models; it also may not be fit
+for further processing by software (e.g. by a PDF distilling program).
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955308"></a>CUPS can use all Windows-formatted Vendor PPDs</h3></div></div><div></div></div><p>
+CUPS can handle all spec-compliant PPDs as supplied by the
+manufacturers for their PostScript models. Even if a
+Unix/Linux-illiterate vendor might not have mentioned our favorite
+OS in his manuals and brochures -- you can safely trust this:
+<span class="emphasis"><em>if you get hold of the Windows NT version of the PPD, you
+can use it unchanged in CUPS</em></span> and thus access the full
+power of your printer just like a Windows NT user could!
+</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+To check the spec compliance of any PPD online, go to <a href="http://www.cups.org/testppd.php" target="_top">http://www.cups.org/testppd.php</a>
+and upload your PPD. You will see the results displayed
+immediately. CUPS in all versions after 1.1.19 has a much more strict
+internal PPD parsing and checking code enabled; in case of printing
+trouble this online resource should be one of your first pitstops.
+</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+For real PostScript printers <span class="emphasis"><em>don't</em></span> use the
+<span class="emphasis"><em>Foomatic</em></span> or <span class="emphasis"><em>cupsomatic</em></span>
+PPDs from Linuxprinting.org. With these devices the original
+vendor-provided PPDs are always the first choice!
+</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+If you are looking for an original vendor-provided PPD of a specific
+device, and you know that an NT4 box (or any other Windows box) on
+your LAN has the PostScript driver installed, just use
+<b class="command">smbclient //NT4-box/print\$ -U username</b> to
+access the Windows directory where all printer driver files are
+stored. First look in the <tt class="filename">W32X86/2</tt> subdir for
+the PPD you are seeking.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955397"></a>CUPS also uses PPDs for non-PostScript Printers</h3></div></div><div></div></div><p>
+CUPS also uses specially crafted PPDs to handle non-PostScript
+printers. These PPDs are usually not available from the vendors (and
+no, you can't just take the PPD of a Postscript printer with the same
+model name and hope it works for the non-PostScript version too). To
+understand how these PPDs work for non-PS printers we first need to
+dive deeply into the CUPS filtering and file format conversion
+architecture. Stay tuned.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2955420"></a>The CUPS Filtering Architecture</h2></div></div><div></div></div><p>
+The core of the CUPS filtering system is based on
+<span class="emphasis"><em>Ghostscript</em></span>. In addition to Ghostscript, CUPS
+uses some other filters of its own. You (or your OS vendor) may have
+plugged in even more filters. CUPS handles all data file formats under
+the label of various <span class="emphasis"><em>MIME types</em></span>. Every incoming
+printfile is subjected to an initial
+<span class="emphasis"><em>auto-typing</em></span>. The auto-typing determines its given
+MIME type. A given MIME type implies zero or more possible filtering
+chains relevant to the selected target printer. This section discusses
+how MIME types recognition and conversion rules interact. They are
+used by CUPS to automatically setup a working filtering chain for any
+given input data format.
+</p><p>
+If CUPS rasterizes a PostScript file <span class="emphasis"><em>natively</em></span> to
+a bitmap, this is done in 2 stages:
+</p><div class="itemizedlist"><ul type="disc"><li><p>the first stage uses a Ghostscript device named &quot;cups&quot;
+(this is since version 1.1.15) and produces a generic raster format
+called &quot;CUPS raster&quot;.
+</p></li><li><p>the second stage uses a &quot;raster driver&quot; which converts
+the generic CUPS raster to a device specific raster.</p></li></ul></div><p>
+Make sure your Ghostscript version has the &quot;cups&quot; device compiled in
+(check with <b class="command">gs -h | grep cups</b>).  Otherwise you
+may encounter the dreaded <tt class="computeroutput">Unable to convert file
+0</tt> in your CUPS error_log file. To have &quot;cups&quot; as a
+device in your Ghostscript, you either need to <span class="emphasis"><em>patch GNU
+Ghostscript</em></span> and re-compile or use <a href="http://www.cups.org/ghostscript.php" target="_top">ESP Ghostscript</a>. The
+superior alternative is ESP Ghostscript: it supports not just CUPS,
+but 300 other devices too (while GNU Ghostscript supports only about
+180). Because of this broad output device support, ESP Ghostscript is
+the first choice for non-CUPS spoolers too. It is now recommended by
+Linuxprinting.org for all spoolers.
+</p><p>
+CUPS printers may be setup to use <span class="emphasis"><em>external</em></span>
+rendering paths. One of the most common ones is provided by the
+<span class="emphasis"><em>Foomatic/cupsomatic</em></span> concept, from <a href="http://www.linuxprinting.org/" target="_top">Linuxprinting.org</a>.  This
+uses the classical Ghostscript approach, doing everything in one
+step. It doesn't use the &quot;cups&quot; device, but one of the many
+others. However, even for Foomatic/cupsomatic usage, best results and
+broadest printer model support is provided by ESP Ghostscript (more
+about cupsomatic/Foomatic, particularly the new version called now
+<span class="emphasis"><em>foomatic-rip</em></span>, follows below).
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955560"></a>MIME types and CUPS Filters</h3></div></div><div></div></div><p>
+CUPS reads the file <tt class="filename">/etc/cups/mime.types</tt>
+(and all other files carrying a <tt class="filename">*.types</tt> suffix
+in the same directory) upon startup. These files contain the MIME
+type recognition rules which are applied when CUPS runs its
+auto-typing routines. The rule syntax is explained in the man page
+for <tt class="filename">mime.types</tt> and in the comments section of the
+<tt class="filename">mime.types</tt> file itself. A simple rule reads
+like this:
+</p><pre class="screen">
+
+ application/pdf         pdf string(0,%PDF)
+
+</pre><p>
+This means: if a filename has either a
+<tt class="filename">.pdf</tt> suffix, or if the magic
+string <span class="emphasis"><em>%PDF</em></span> is right at the
+beginning of the file itself (offset 0 from the start), then it is
+a PDF file (<span class="emphasis"><em>application/pdf</em></span>).
+Another rule is this: 
+</p><pre class="screen">
+
+ application/postscript  ai eps ps string(0,%!) string(0,&lt;04&gt;%!)
+
+</pre><p>
+Its meaning: if the filename has one of the suffixes
+<tt class="filename">.ai</tt>, <tt class="filename">.eps</tt>,
+<tt class="filename">.ps</tt> or if the file itself starts with one of the
+strings <span class="emphasis"><em>%!</em></span> or <span class="emphasis"><em>&lt;04&gt;%!</em></span>, it
+is a generic PostScript file
+(<span class="emphasis"><em>application/postscript</em></span>).
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+There is a very important difference between two similar MIME type in
+CUPS: one is <span class="emphasis"><em>application/postscript</em></span>, the other is
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span>. While
+<span class="emphasis"><em>application/postscript</em></span> is meant to be device
+independent (job options for the file are still outside the PS file
+content, embedded in commandline or environment variables by CUPS),
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span> may have the job
+options inserted into the PostScript data itself (were
+applicable). The transformation of the generic PostScript
+(application/postscript) to the device-specific version
+(application/vnd.cups-postscript) is the responsibility of the
+CUPS <span class="emphasis"><em>pstops</em></span> filter. pstops uses information
+contained in the PPD to do the transformation.
+</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+Don't confuse the other mime.types file your system might be using
+with the one in the <tt class="filename">/etc/cups/</tt> directory.
+</p></div><p>
+CUPS can handle ASCII text, HP-GL, PDF, PostScript, DVI and a
+lot of image formats (GIF. PNG, TIFF, JPEG, Photo-CD, SUN-Raster,
+PNM, PBM, SGI-RGB and some more) and their associated MIME types
+with its filters.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955747"></a>MIME type Conversion Rules</h3></div></div><div></div></div><p>
+CUPS reads the file <tt class="filename">/etc/cups/mime.convs</tt>
+(and all other files named with a <tt class="filename">*.convs</tt>
+suffix in the same directory) upon startup. These files contain
+lines naming an input MIME type, an output MIME type, a format
+conversion filter which can produce the output from the input type
+and virtual costs associated with this conversion. One example line
+reads like this:
+</p><pre class="screen">
+
+ application/pdf         application/postscript   33   pdftops
+
+</pre><p>
+This means that the <span class="emphasis"><em>pdftops</em></span> filter will take
+<span class="emphasis"><em>application/pdf</em></span> as input and produce
+<span class="emphasis"><em>application/postscript</em></span> as output, the virtual
+cost of this operation is 33 CUPS-$. The next filter is more
+expensive, costing 66 CUPS-$:
+</p><pre class="screen">
+
+ application/vnd.hp-HPGL application/postscript   66   hpgltops
+
+</pre><p>
+This is the <span class="emphasis"><em>hpgltops</em></span>, which processes HP-GL
+plotter files to PostScript.
+</p><pre class="screen">
+
+ application/octet-stream
+
+</pre><p>
+Here are two more examples: 
+</p><pre class="screen">
+
+ application/x-shell     application/postscript   33    texttops
+ text/plain              application/postscript   33    texttops
+
+</pre><p>
+The last two examples name the <span class="emphasis"><em>texttops</em></span> filter
+to work on &quot;text/plain&quot; as well as on &quot;application/x-shell&quot;. (Hint:
+this differentiation is needed for the syntax highlighting feature of
+&quot;texttops&quot;).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2955864"></a>Filter Requirements</h3></div></div><div></div></div><p>
+There are many more combinations named in mime.convs.  However, you
+are not limited to use the ones pre-defined there. You can plug in any
+filter you like into the CUPS framework. It must meet, or must be made
+to meet some minimal requirements. If you find (or write) a cool
+conversion filter of some kind, make sure it complies to what CUPS
+needs, and put in the right lines in <tt class="filename">mime.types</tt>
+and <tt class="filename">mime.convs</tt>, then it will work seamlessly
+inside CUPS!
+</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+The mentioned &quot;CUPS requirements&quot; for filters are simple. Take
+filenames or <tt class="filename">stdin</tt> as input and write to
+<tt class="filename">stdout</tt>. They should take these 5 or 6 arguments:
+<span class="emphasis"><em>printer job user title copies options [filename]</em></span>
+</p><div class="variablelist"><dl><dt><span class="term">Printer</span></dt><dd><p>The name of the printer queue (normally this is the
+name of the filter being run)</p></dd><dt><span class="term">job</span></dt><dd><p>The numeric job ID for the job being
+printed</p></dd><dt><span class="term">Printer</span></dt><dd><p>The string from the originating-user-name
+attribute</p></dd><dt><span class="term">Printer</span></dt><dd><p>The string from the job-name attribute</p></dd><dt><span class="term">Printer</span></dt><dd><p>The numeric value from the number-copies
+attribute</p></dd><dt><span class="term">Printer</span></dt><dd><p>The job options</p></dd><dt><span class="term">Printer</span></dt><dd><p>(Optionally) The print request file (if missing,
+filters expected data fed through <tt class="filename">stdin</tt>). In most
+cases it is very easy to write a simple wrapper script around existing
+filters to make them work with CUPS.</p></dd></dl></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956034"></a>Prefilters</h3></div></div><div></div></div><p>
+As was said, PostScript is the central file format to any Unix based
+printing system. From PostScript, CUPS generates raster data to feed
+non-PostScript printers.
+</p><p>
+But what is happening if you send one of the supported non-PS formats
+to print? Then CUPS runs &quot;pre-filters&quot; on these input formats to
+generate PostScript first. There are pre-filters to create PS from
+ASCII text, PDF, DVI or HP-GL. The outcome of these filters is always
+of MIME type <span class="emphasis"><em>application/postscript</em></span> (meaning that
+any device-specific print options are not yet embedded into the
+PostScript by CUPS, and that the next filter to be called is
+pstops). Another pre-filter is running on all supported image formats,
+the <span class="emphasis"><em>imagetops</em></span> filter. Its outcome is always of
+MIME type <span class="emphasis"><em>application/vnd.cups-postscript</em></span>
+(<span class="emphasis"><em>not</em></span> application/postscript), meaning it has the
+print options already embedded into the file.
+</p><p>
+</p><div class="figure"><a name="id2956084"></a><p class="title"><b>Figure 19.4. Prefiltering in CUPS to form Postscript</b></p><div class="mediaobject"><img src="projdoc/imagefiles/4small.png" alt="Prefiltering in CUPS to form Postscript"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956120"></a>pstops</h3></div></div><div></div></div><p>
+<span class="emphasis"><em>pstops</em></span>is the filter to convert
+<span class="emphasis"><em>application/postscript</em></span> to
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span>. It was said
+above that this filter inserts all device-specific print options
+(commands to the printer to ask for the duplexing of output, or
+stapling an punching it, etc.) into the PostScript file.
+</p><p>
+</p><div class="figure"><a name="id2956149"></a><p class="title"><b>Figure 19.5. Adding Device-specific Print Options</b></p><div class="mediaobject"><img src="projdoc/imagefiles/5small.png" alt="Adding Device-specific Print Options"></div></div><p>
+</p><p>
+This is not all: other tasks performed by it are:
+</p><div class="itemizedlist"><ul type="disc"><li><p>
+selecting the range of pages to be printed (if you choose to
+print only pages &quot;3, 6, 8-11, 16, 19-21&quot;, or only the odd numbered
+ones)
+</p></li><li><p>
+putting 2 or more logical pages on one sheet of paper (the
+so-called &quot;number-up&quot; function)
+</p></li><li><p>counting the pages of the job to insert the accounting
+information into the <tt class="filename">/var/log/cups/page_log</tt>
+</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956222"></a>pstoraster</h3></div></div><div></div></div><p>
+<span class="emphasis"><em>pstoraster</em></span> is at the core of the CUPS filtering
+system. It is responsible for the first stage of the rasterization
+process. Its input is of MIME type application/vnd.cups-postscript;
+its output is application/vnd.cups-raster. This output format is not
+yet meant to be printable. Its aim is to serve as a general purpose
+input format for more specialized <span class="emphasis"><em>raster drivers</em></span>,
+that are able to generate device-specific printer data.
+</p><p>
+</p><div class="figure"><a name="id2956251"></a><p class="title"><b>Figure 19.6. Postscript to intermediate Raster format</b></p><div class="mediaobject"><img src="projdoc/imagefiles/6small.png" alt="Postscript to intermediate Raster format"></div></div><p>
+</p><p>
+CUPS raster is a generic raster format with powerful features. It is
+able to include per-page information, color profiles and more to be
+used by the following downstream raster drivers. Its MIME type is
+registered with IANA and its specification is of course completely
+open. It is designed to make it very easy and inexpensive for
+manufacturers to develop Linux and Unix raster drivers for their
+printer models, should they choose to do so. CUPS always takes care
+for the first stage of rasterization so these vendors don't need to care
+about Ghostscript complications (in fact, there is currently more
+than one vendor financing the development of CUPS raster drivers).
+</p><p>
+</p><div class="figure"><a name="id2956304"></a><p class="title"><b>Figure 19.7. CUPS-raster production using Ghostscript</b></p><div class="mediaobject"><img src="projdoc/imagefiles/7small.png" alt="CUPS-raster production using Ghostscript"></div></div><p>
+</p><p>
+CUPS versions before version 1.1.15 were shipping a binary (or source
+code) standalone filter, named &quot;pstoraster&quot;. pstoraster was derived
+from GNU Ghostscript 5.50, and could be installed besides and in
+addition to any GNU or AFPL Ghostscript package without conflicting.
+</p><p>
+From version 1.1.15, this has changed. The functions for this has been
+integrated back into Ghostscript (now based on GNU Ghostscript version
+7.05). The &quot;pstoraster&quot; filter is now a simple shell script calling
+<b class="command">gs</b> with the <b class="command">-sDEVICE=cups</b>
+parameter. If your Ghostscript doesn't show a success on asking for
+<b class="command">gs -h |grep cups</b>, you might not be able to
+print. Update your Ghostscript then!
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956377"></a>imagetops and imagetoraster</h3></div></div><div></div></div><p>
+Above in the section about prefilters, we mentioned the prefilter
+that generates PostScript from image formats. The imagetoraster
+filter is used to convert directly from image to raster, without the
+intermediate PostScript stage. It is used more often than the above
+mentioned prefilters. Here is a summarizing flowchart of image file
+filtering:
+</p><p>
+</p><div class="figure"><a name="id2956398"></a><p class="title"><b>Figure 19.8. Image format to CUPS-raster format conversion</b></p><div class="mediaobject"><img src="projdoc/imagefiles/8small.png" alt="Image format to CUPS-raster format conversion"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956434"></a>rasterto [printers specific]</h3></div></div><div></div></div><p>
+CUPS ships with quite some different raster drivers processing CUPS
+raster. On my system I find in /usr/lib/cups/filter/ these:
+<i class="parameter"><tt>rastertoalps, rastertobj, rastertoepson, rastertoescp,
+rastertopcl, rastertoturboprint, rastertoapdk, rastertodymo,
+rastertoescp, rastertohp</tt></i> and
+<i class="parameter"><tt>rastertoprinter</tt></i>. Don't worry if you have less
+than this; some of these are installed by commercial add-ons to CUPS
+(like <i class="parameter"><tt>rastertoturboprint</tt></i>), others (like
+<i class="parameter"><tt>rastertoprinter</tt></i>) by 3rd party driver
+development projects (such as Gimp-Print) wanting to cooperate as
+closely as possible with CUPS.
+</p><p>
+</p><div class="figure"><a name="id2956484"></a><p class="title"><b>Figure 19.9. Raster to Printer Specific formats</b></p><div class="mediaobject"><img src="projdoc/imagefiles/9small.png" alt="Raster to Printer Specific formats"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956519"></a>CUPS Backends</h3></div></div><div></div></div><p>
+The last part of any CUPS filtering chain is a &quot;backend&quot;.  Backends
+are special programs that send the print-ready file to the final
+device. There is a separate backend program for any transfer
+&quot;protocol&quot; of sending printjobs over the network, or for every local
+interface. Every CUPS printqueue needs to have a CUPS &quot;device-URI&quot;
+associated with it. The device URI is the way to encode the backend
+used to send the job to its destination. Network device-URIs are using
+two slashes in their syntax, local device URIs only one, as you can
+see from the following list. Keep in mind that local interface names
+may vary much from my examples, if your OS is not Linux:
+</p><div class="variablelist"><dl><dt><span class="term">usb</span></dt><dd><p>
+This backend sends printfiles to USB-connected printers. An
+example for the CUPS device-URI to use is:
+<tt class="filename">usb:/dev/usb/lp0</tt>
+</p></dd><dt><span class="term">serial</span></dt><dd><p>
+This backend sends printfiles to serially connected printers.
+An example for the CUPS device-URI to use is:
+<tt class="filename">serial:/dev/ttyS0?baud=11500</tt>
+</p></dd><dt><span class="term">parallel</span></dt><dd><p>
+This backend sends printfiles to printers connected to the
+parallel port. An example for the CUPS device-URI to use is:
+<tt class="filename">parallel:/dev/lp0</tt>
+</p></dd><dt><span class="term">scsi</span></dt><dd><p>
+This backend sends printfiles to printers attached to the
+SCSI interface. An example for the CUPS device-URI to use is:
+<tt class="filename">scsi:/dev/sr1</tt>
+</p></dd><dt><span class="term">lpd</span></dt><dd><p>
+This backend sends printfiles to LPR/LPD connected network
+printers. An example for the CUPS device-URI to use is:
+<tt class="filename">lpd://remote_host_name/remote_queue_name</tt>
+</p></dd><dt><span class="term">AppSocket/HP JetDirect</span></dt><dd><p>
+This backend sends printfiles to AppSocket (a.k.a. &quot;HP
+JetDirect&quot;) connected network printers. An example for the CUPS
+device-URI to use is:
+<tt class="filename">socket://10.11.12.13:9100</tt>
+</p></dd><dt><span class="term">ipp</span></dt><dd><p>
+This backend sends printfiles to IPP connected network
+printers (or to other CUPS servers). Examples for CUPS device-URIs
+to use are:
+<tt class="filename">ipp:://192.193.194.195/ipp</tt>
+(for many HP printers) or
+<tt class="filename">ipp://remote_cups_server/printers/remote_printer_name</tt>
+</p></dd><dt><span class="term">http</span></dt><dd><p>
+This backend sends printfiles to HTTP connected printers.
+(The http:// CUPS backend is only a symlink to the ipp:// backend.)
+Examples for the CUPS device-URIs to use are:
+<tt class="filename">http:://192.193.194.195:631/ipp</tt>
+(for many HP printers) or
+<tt class="filename">http://remote_cups_server:631/printers/remote_printer_name</tt>
+</p></dd><dt><span class="term">smb</span></dt><dd><p>
+This backend sends printfiles to printers shared by a Windows
+host. An example for CUPS device-URIs to use are:
+<tt class="filename">smb://workgroup/server/printersharename</tt>
+Or
+<tt class="filename">Smb://server/printersharename</tt>
+or
+<tt class="filename">smb://username:password@workgroup/server/printersharename</tt>
+or
+<tt class="filename">smb://username:password@server/printersharename</tt>.
+The smb:// backend is a symlink to the Samba utility
+<span class="emphasis"><em>smbspool</em></span> (doesn't ship with CUPS). If the
+symlink is not present in your CUPS backend directory, have your
+root user create it: <b class="command">ln -s `which smbspool`
+/usr/lib/cups/backend/smb</b>.
+</p></dd></dl></div><p>
+It is easy to write your own backends as Shell or Perl scripts, if you
+need any modification or extension to the CUPS print system. One
+reason could be that you want to create &quot;special&quot; printers which send
+the printjobs as email (through a &quot;mailto:/&quot; backend), convert them to
+PDF (through a &quot;pdfgen:/&quot; backend) or dump them to &quot;/dev/null&quot; (In
+fact I have the system-wide default printer set up to be connected to
+a &quot;devnull:/&quot; backend: there are just too many people sending jobs
+without specifying a printer, or scripts and programs which don't name
+a printer. The system-wide default deletes the job and sends a polite
+mail back to the $USER asking him to always specify a correct
+printername).
+</p><p>
+Not all of the mentioned backends may be present on your system or
+usable (depending on your hardware configuration). One test for all
+available CUPS backends is provided by the <span class="emphasis"><em>lpinfo</em></span>
+utility. Used with the <i class="parameter"><tt>-v</tt></i> parameter, it lists
+all available backends:
+</p><pre class="screen">
+
+ lpinfo -v
+
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956831"></a>cupsomatic/Foomatic -- how do they fit into the Picture?</h3></div></div><div></div></div><p>
+&quot;cupsomatic&quot; filters may be the most widely used on CUPS
+installations. You must be clear about the fact that these were not
+developed by the CUPS people. They are a &quot;Third Party&quot; add-on to
+CUPS. They utilize the traditional Ghostscript devices to render jobs
+for CUPS. When troubleshooting, you should know about the
+difference. Here the whole rendering process is done in one stage,
+inside Ghostscript, using an appropriate &quot;device&quot; for the target
+printer. cupsomatic uses PPDs which are generated from the &quot;Foomatic&quot;
+Printer &amp; Driver Database at Linuxprinting.org.
+</p><p>
+You can recognize these PPDs from the line calling the
+<span class="emphasis"><em>cupsomatic</em></span> filter:
+</p><pre class="screen">
+
+ *cupsFilter: &quot;application/vnd.cups-postscript  0  cupsomatic&quot;
+
+</pre><p>
+This line you may find amongst the first 40 or so lines of the PPD
+file. If you have such a PPD installed, the printer shows up in the
+CUPS web interface with a <span class="emphasis"><em>foomatic</em></span> namepart for
+the driver description. cupsomatic is a Perl script that runs
+Ghostscript, with all the complicated commandline options
+auto-constructed from the selected PPD and commandline options give to
+the printjob.
+</p><p>
+However, cupsomatic is now deprecated. Its PPDs (especially the first
+generation of them, still in heavy use out there) are not meeting the
+Adobe specifications. You might also suffer difficulties when you try
+to download them with &quot;Point'n'Print&quot; to Windows clients. A better,
+and more powerful successor is now in a very stable Beta-version
+available: it is called <span class="emphasis"><em>foomatic-rip</em></span>. To use
+foomatic-rip as a filter with CUPS, you need the new-type PPDs.  These
+have a similar, but different line:
+</p><pre class="screen">
+
+ *cupsFilter: &quot;application/vnd.cups-postscript  0  foomatic-rip&quot;
+
+</pre><p>
+The PPD generating engine at Linuxprinting.org has been revamped.
+The new PPDs comply to the Adobe spec. On top, they also provide a
+new way to specify different quality levels (hi-res photo, normal
+color, grayscale, draft...) with a single click (whereas before you
+could have required 5 or more different selections (media type,
+resolution, inktype, dithering algorithm...). There is support for
+custom-size media built in. There is support to switch
+print-options from page to page, in the middle of a job. And the
+best thing is: the new foomatic-rip now works seamlessly with all
+legacy spoolers too (like LPRng, BSD-LPD, PDQ, PPR etc.), providing
+for them access to use PPDs for their printing!
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956944"></a>The Complete Picture</h3></div></div><div></div></div><p>
+If you want to see an overview over all the filters and how they
+relate to each other, the complete picture of the puzzle is at the end
+of this document.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2956960"></a><tt class="filename">mime.convs</tt></h3></div></div><div></div></div><p>
+CUPS auto-constructs all possible filtering chain paths for any given
+MIME type, and every printer installed. But how does it decide in
+favor or against a specific alternative?  (There may often be cases,
+where there is a choice of two or more possible filtering chains for
+the same target printer). Simple: you may have noticed the figures in
+the 3rd column of the mime.convs file. They represent virtual costs
+assigned to this filter. Every possible filtering chain will sum up to
+a total &quot;filter cost&quot;. CUPS decides for the most &quot;inexpensive&quot; route.
+</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+The setting of <i class="parameter"><tt>FilterLimit 1000</tt></i> in
+<tt class="filename">cupsd.conf</tt> will not allow more filters to
+run concurrently than will consume a total of 1000 virtual filter
+cost. This is a very efficient way to limit the load of any CUPS
+server by setting an appropriate &quot;FilterLimit&quot; value. A FilterLimit of
+200 allows roughly 1 job at a time, while a FilterLimit of 1000 allows
+approximately 5 jobs maximum at a time.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957012"></a>&quot;Raw&quot; printing</h3></div></div><div></div></div><p>
+You can tell CUPS to print (nearly) any file &quot;raw&quot;. &quot;Raw&quot; means it
+will not be filtered. CUPS will send the file to the printer &quot;as is&quot;
+without bothering if the printer is able to digest it. Users need to
+take care themselves that they send sensible data formats only. Raw
+printing can happen on any queue if the &quot;-o raw&quot; option is specified
+on the command line. You can also set up raw-only queues by simply not
+associating any PPD with it. This command:
+</p><pre class="screen">
+
+ lpadmin -P rawprinter -v socket://11.12.13.14:9100 -E
+
+</pre><p>
+sets up a queue named &quot;rawprinter&quot;, connected via the &quot;socket&quot;
+protocol (a.k.a. &quot;HP JetDirect&quot;) to the device at IP address
+11.12.1.3.14, using port 9100. (If you had added a PPD with
+<b class="command">-P /path/to/PPD</b> to this command line, you would
+have installed a &quot;normal&quot; printqueue.
+</p><p>
+CUPS will automatically treat each job sent to a queue as a &quot;raw&quot; one,
+if it can't find a PPD associated with the queue.  However, CUPS will
+only send known MIME types (as defined in its own mime.types file) and
+refuse others.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957066"></a>&quot;application/octet-stream&quot; printing</h3></div></div><div></div></div><p>
+Any MIME type with no rule in the
+<tt class="filename">/etc/cups/mime.types</tt> file is regarded as unknown
+or <span class="emphasis"><em>application/octet-stream</em></span> and will not be
+sent. Because CUPS refuses to print unknown MIME types per default,
+you will probably have experienced the fact that printjobs originating
+from Windows clients were not printed. You may have found an error
+message in your CUPS logs like:
+</p><pre class="screen">
+
+ Unable to convert file 0 to printable format for job
+
+</pre><p>
+To enable the printing of &quot;application/octet-stream&quot; files, edit
+these two files:
+</p><div class="itemizedlist"><ul type="disc"><li><p><tt class="filename">/etc/cups/mime.convs</tt></p></li><li><p><tt class="filename">/etc/cups/mime.types</tt></p></li></ul></div><p>
+Both contain entries (at the end of the respective files) which must
+be uncommented to allow RAW mode operation for
+application/octet-stream. In <tt class="filename">/etc/cups/mime.types</tt>
+make sure this line is present:
+</p><pre class="screen">
+
+ application/octet-stream
+
+</pre><p>
+This line (with no specific auto-typing rule set) makes all files
+not otherwise auto-typed a member of application/octet-stream. In
+<tt class="filename">/etc/cups/mime.convs</tt>, have this
+line: 
+</p><pre class="screen">
+
+ application/octet-stream   application/vnd.cups-raw   0   -
+
+</pre><p>
+This line tells CUPS to use the <span class="emphasis"><em>Null Filter</em></span>
+(denoted as &quot;-&quot;, doing... nothing at all) on
+<span class="emphasis"><em>application/octet-stream</em></span>, and tag the result as
+<span class="emphasis"><em>application/vnd.cups-raw</em></span>. This last one is
+always a green light to the CUPS scheduler to now hand the file over
+to the &quot;backend&quot; connecting to the printer and sending it over.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> Editing the <tt class="filename">mime.convs</tt> and the
+<tt class="filename">mime.types</tt> file does not
+<span class="emphasis"><em>enforce</em></span> &quot;raw&quot; printing, it only
+<span class="emphasis"><em>allows</em></span> it.
+</p></div><p><b>Background. </b>
+CUPS being a more security-aware printing system than traditional ones
+does not by default allow one to send deliberate (possibly binary)
+data to printing devices.  (This could be easily abused to launch a
+Denial of Service attack on your printer(s), causing at least the loss
+of a lot of paper and ink...) &quot;Unknown&quot; data are regarded by CUPS
+as <span class="emphasis"><em>MIME type</em></span>
+<span class="emphasis"><em>application/octet-stream</em></span>. While you
+<span class="emphasis"><em>can</em></span> send data &quot;raw&quot;, the MIME type for these must
+be one that is known to CUPS and an allowed one. The file
+<tt class="filename">/etc/cups/mime.types</tt> defines the &quot;rules&quot; how CUPS
+recognizes MIME types. The file
+<tt class="filename">/etc/cups/mime.convs</tt> decides which file
+conversion filter(s) may be applied to which MIME types.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957282"></a>PostScript Printer Descriptions (PPDs) for non-PS Printers</h3></div></div><div></div></div><p>
+Originally PPDs were meant to be used for PostScript printers
+only. Here, they help to send device-specific commands and settings
+to the RIP which processes the jobfile. CUPS has extended this
+scope for PPDs to cover non-PostScript printers too. This was not
+very difficult, because it is a standardized file format. In a way
+it was logical too: CUPS handles PostScript and uses a PostScript
+RIP (=Ghostscript) to process the jobfiles. The only difference is:
+a PostScript printer has the RIP built-in, for other types of
+printers the Ghostscript RIP runs on the host computer.
+</p><p>
+PPDs for a non-PS printer have a few lines that are unique to
+CUPS. The most important one looks similar to this:
+</p><pre class="screen">
+
+ *cupsFilter: application/vnd.cups-raster  66   rastertoprinter
+
+</pre><p>
+It is the last piece in the CUPS filtering puzzle. This line tells the
+CUPS daemon to use as a last filter &quot;rastertoprinter&quot;.  This filter
+should be served as input an &quot;application/vnd.cups-raster&quot; MIME type
+file. Therefore CUPS should auto-construct a filtering chain, which
+delivers as its last output the specified MIME type. This is then
+taken as input to the specified &quot;rastertoprinter&quot; filter. After this
+the last filter has done its work (&quot;rastertoprinter&quot; is a Gimp-Print
+filter), the file should go to the backend, which sends it to the
+output device.
+</p><p>
+CUPS by default ships only a few generic PPDs, but they are good for
+several hundred printer models. You may not be able to control
+different paper trays, or you may get larger margins than your
+specific model supports):
+</p><div class="variablelist"><dl><dt><span class="term">deskjet.ppd</span></dt><dd><p>older HP inkjet printers and compatible
+</p></dd><dt><span class="term">deskjet2.ppd</span></dt><dd><p>newer HP inkjet printers and compatible
+</p></dd><dt><span class="term">dymo.ppd</span></dt><dd><p>label printers
+</p></dd><dt><span class="term">epson9.ppd</span></dt><dd><p>Epson 24pin impact printers and compatible
+</p></dd><dt><span class="term">epson24.ppd</span></dt><dd><p>Epson 24pin impact printers and compatible
+</p></dd><dt><span class="term">okidata9.ppd</span></dt><dd><p>Okidata 9pin impact printers and compatible
+</p></dd><dt><span class="term">okidat24.ppd</span></dt><dd><p>Okidata 24pin impact printers and compatible
+</p></dd><dt><span class="term">stcolor.ppd</span></dt><dd><p>older Epson Stylus Color printers
+</p></dd><dt><span class="term">stcolor2.ppd</span></dt><dd><p>newer Epson Stylus Color printers
+</p></dd><dt><span class="term">stphoto.ppd</span></dt><dd><p>older Epson Stylus Photo printers
+</p></dd><dt><span class="term">stphoto2.ppd</span></dt><dd><p>newer Epson Stylus Photo printers
+</p></dd><dt><span class="term">laserjet.ppd</span></dt><dd><p>all PCL printers. Further below is a discussion
+of several other driver/PPD-packages suitable fur use with CUPS.
+</p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957510"></a>Difference between <span class="emphasis"><em>cupsomatic/foomatic-rip</em></span> and
+<span class="emphasis"><em>native CUPS</em></span> printing</h3></div></div><div></div></div><p>
+Native CUPS rasterization works in two steps.
+</p><div class="itemizedlist"><ul type="disc"><li><p>
+First is the &quot;pstoraster&quot; step. It uses the special &quot;cups&quot;
+device from ESP Ghostscript 7.05.x as its tool
+</p></li><li><p>
+Second comes the &quot;rasterdriver&quot; step. It uses various
+device-specific filters; there are several vendors who provide good
+quality filters for this step, some are Free Software, some are
+Shareware/Non-Free, some are proprietary.</p></li></ul></div><p>
+Often this produces better quality (and has several more
+advantages) than other methods.
+</p><p>
+</p><div class="figure"><a name="id2957561"></a><p class="title"><b>Figure 19.10. cupsomatic/foomatic processing versus Native CUPS</b></p><div class="mediaobject"><img src="projdoc/imagefiles/10small.png" alt="cupsomatic/foomatic processing versus Native CUPS"></div></div><p>
+</p><p>
+One other method is the <span class="emphasis"><em>cupsomatic/foomatic-rip</em></span>
+way. Note that cupsomatic is <span class="emphasis"><em>not</em></span> made by the CUPS
+developers. It is an independent contribution to printing development,
+made by people from Linuxprinting.org (see also <a href="http://www.cups.org/cups-help.html" target="_top">http://www.cups.org/cups-help.html</a>).
+cupsomatic is no longer developed and maintained and is no longer
+supported. It has now been replaced by
+<span class="emphasis"><em>foomatic-rip</em></span>. foomatic-rip is a complete re-write
+of the old cupsomatic idea, but very much improved and generalized to
+other (non-CUPS) spoolers. An upgrade to foomatic-rip is strongly
+advised, especially if you are upgrading to a recent version of CUPS
+too.
+</p><p>
+Both the cupsomatic (old) and the foomatic-rip (new) methods from
+Linuxprinting.org use the traditional Ghostscript print file
+processing, doing everything in a single step. It therefore relies on
+all the other devices built-in into Ghostscript. The quality is as
+good (or bad) as Ghostscript rendering is in other spoolers. The
+advantage is that this method supports many printer models not
+supported (yet) by the more modern CUPS method.
+</p><p>
+Of course, you can use both methods side by side on one system (and
+even for one printer, if you set up different queues), and find out
+which works best for you.
+</p><p>
+cupsomatic &quot;kidnaps&quot; the printfile after the
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span> stage and
+deviates it through the CUPS-external, system wide Ghostscript
+installation: Therefore the printfile bypasses the &quot;pstoraster&quot; filter
+(and thus also bypasses the CUPS-raster-drivers
+&quot;rastertosomething&quot;). After Ghostscript finished its rasterization,
+cupsomatic hands the rendered file directly to the CUPS backend. The
+flowchart above illustrates the difference between native CUPS
+rendering and the Foomatic/cupsomatic method.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957666"></a>Examples for filtering Chains</h3></div></div><div></div></div><p>
+Here are a few examples of commonly occurring filtering chains to
+illustrate the workings of CUPS.
+</p><p>
+Assume you want to print a PDF file to a HP JetDirect-connected
+PostScript printer, but you want to print the pages 3-5, 7, 11-13
+only, and you want to print them &quot;2-up&quot; and &quot;duplex&quot;:
+</p><div class="itemizedlist"><ul type="disc"><li><p>your print options (page selection as required, 2-up,
+duplex) are passed to CUPS on the commandline;</p></li><li><p>the (complete) PDF file is sent to CUPS and autotyped as
+<span class="emphasis"><em>application/pdf</em></span>;</p></li><li><p>the file therefore first must pass the
+<span class="emphasis"><em>pdftops</em></span> pre-filter, which produces PostScript
+MIME type <span class="emphasis"><em>application/postscript</em></span> (a preview here
+would still show all pages of the original PDF);</p></li><li><p>the file then passes the <span class="emphasis"><em>pstops</em></span>
+filter which applies the commandline options: it selects the pages
+2-5, 7 and 11-13, creates and imposed layout &quot;2 pages on 1 sheet&quot; and
+inserts the correct &quot;duplex&quot; command (as is defined in the printer's
+PPD) into the new PostScript file; the file now is of PostScript MIME
+type
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span>;</p></li><li><p>the file goes to the <span class="emphasis"><em>socket</em></span>
+backend, which transfers the job to the printers.</p></li></ul></div><p>
+The resulting filter chain therefore is:
+</p><pre class="screen">
+pdftops --&gt; pstops --&gt; socket
+</pre><p>
+Assume your want to print the same filter to an USB-connected
+Epson Stylus Photo printer, installed with the CUPS
+<tt class="filename">stphoto2.ppd</tt>. The first few filtering stages
+are nearly the same:
+</p><div class="itemizedlist"><ul type="disc"><li><p>your print options (page selection as required, 2-up,
+duplex) are passed to CUPS on the commandline;</p></li><li><p>the (complete) PDF file is sent to CUPS and autotyped as
+<span class="emphasis"><em>application/pdf</em></span>;</p></li><li><p>the file therefore first must pass the
+<span class="emphasis"><em>pdftops</em></span> pre-filter, which produces PostScript
+MIME type <span class="emphasis"><em>application/postscript</em></span> (a preview here
+would still show all pages of the original PDF);</p></li><li><p>the file then passes the &quot;pstops&quot; filter which applies
+the commandline options: it selects the pages 2-5, 7 and 11-13,
+creates and imposed layout &quot;2 pages on 1 sheet&quot; and inserts the
+correct &quot;duplex&quot; command... (OOoops -- this printer and his PPD
+don't support duplex printing at all -- this option will be ignored
+then) into the new PostScript file; the file now is of PostScript
+MIME type 
+<span class="emphasis"><em>application/vnd.cups-postscript</em></span>;</p></li><li><p>the file then passes the
+<span class="emphasis"><em>pstoraster</em></span> stage and becomes MIME type
+<span class="emphasis"><em>application/cups-raster</em></span>;</p></li><li><p>finally, the <span class="emphasis"><em>rastertoepson</em></span> filter
+does its work (as is indicated in the printer's PPD), creating the
+printer-specific raster data and embedding any user-selected
+print-options into the print data stream;</p></li><li><p>the file goes to the <span class="emphasis"><em>usb</em></span> backend,
+which transfers the job to the printers.</p></li></ul></div><p>
+The resulting filter chain therefore is:
+</p><pre class="screen">
+pdftops --&gt; pstops --&gt; pstoraster --&gt; rastertoepson --&gt; usb
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2957897"></a>Sources of CUPS drivers / PPDs</h3></div></div><div></div></div><p>
+On the internet you can find now many thousand CUPS-PPD files
+(with their companion filters), in many national languages,
+supporting more than 1000 non-PostScript models.
+</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://wwwl.easysw.com/printpro/" target="_top">ESP
+PrintPro (http://wwwl.easysw.com/printpro/)</a> (commercial,
+non-Free) is packaged with more than 3000 PPDs, ready for
+successful use &quot;out of the box&quot; on Linux, Mac OS X, IBM-AIX,
+HP-UX, Sun-Solaris, SGI-IRIX, Compaq Tru64, Digital Unix and some
+more commercial Unices (it is written by the CUPS developers
+themselves and its sales help finance the further development of
+CUPS, as they feed their creators).</p></li><li><p>the <a href="http://gimp-print.sourceforge.net/" target="_top">Gimp-Print-Project
+(http://gimp-print.sourceforge.net/)</a> (GPL, Free Software)
+provides around 140 PPDs (supporting nearly 400 printers, many driven
+to photo quality output), to be used alongside the Gimp-Print CUPS
+filters;</p></li><li><p><a href="http://www.turboprint.com/" target="_top">TurboPrint
+(http://www.turboprint.com/)</a> (Shareware, non-Free) supports
+roughly the same amount of printers in excellent
+quality;</p></li><li><p><a href="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/" target="_top">OMNI
+(http://www-124.ibm.com/developerworks/oss/linux/projects/omni/)</a>
+(LPGL, Free) is a package made by IBM, now containing support for more
+than 400 printers, stemming from the inheritance of IBM OS/2 Know-How
+ported over to Linux (CUPS support is in a Beta-stage at
+present);</p></li><li><p><a href="http://hpinkjet.sourceforge.net/" target="_top">HPIJS
+(http://hpinkjet.sourceforge.net/)</a> (BSD-style licenses, Free)
+supports around 150 of HP's own printers and is also providing
+excellent print quality now (currently available only via the Foomatic
+path);</p></li><li><p><a href="http://www.linuxprinting.org/" target="_top">Foomatic/cupsomatic
+(http://www.linuxprinting.org/)</a> (LPGL, Free) from
+Linuxprinting.org are providing PPDs for practically every Ghostscript
+filter known to the world (including Omni, Gimp-Print and
+HPIJS).</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+The cupsomatic/Foomatic trick from Linuxprinting.org works
+differently from the other drivers. This is explained elsewhere in this
+document.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958024"></a>Printing with Interface Scripts</h3></div></div><div></div></div><p>
+CUPS also supports the usage of &quot;interface scripts&quot; as known from
+System V AT&amp;T printing systems. These are often used for PCL
+printers, from applications that generate PCL print jobs.  Interface
+scripts are specific to printer models. They have a similar role as
+PPDs for PostScript printers. Interface scripts may inject the Escape
+sequences as required into the print data stream, if the user has
+chosen to select a certain paper tray, or print landscape, or use A3
+paper, etc. Interfaces scripts are practically unknown in the Linux
+realm. On HP-UX platforms they are more often used. You can use any
+working interface script on CUPS too. Just install the printer with
+the <b class="command">-i</b> option:
+</p><pre class="screen">
+
+ lpadmin -p pclprinter -v socket://11.12.13.14:9100 -i /path/to/interface-script
+
+</pre><p>
+Interface scripts might be the &quot;unknown animal&quot; to many.  However,
+with CUPS they provide the most easy way to plug in your own
+custom-written filtering script or program into one specific print
+queue (some information about the traditional usage of interface scripts is
+to be found at <a href="http://playground.sun.com/printing/documentation/interface.html" target="_top">http://playground.sun.com/printing/documentation/interface.html</a>).
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2958100"></a>Network printing (purely Windows)</h2></div></div><div></div></div><p>
+Network printing covers a lot of ground. To understand what exactly
+goes on with Samba when it is printing on behalf of its Windows
+clients, let's first look at a &quot;purely Windows&quot; setup: Windows clients
+with a Windows NT print server.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958116"></a>From Windows Clients to an NT Print Server</h3></div></div><div></div></div><p>
+Windows clients printing to an NT-based print server have two
+options. They may
+</p><div class="itemizedlist"><ul type="disc"><li><p>execute the driver locally and render the GDI output
+(EMF) into the printer specific format on their own,
+or</p></li><li><p>send the GDI output (EMF) to the server, where the
+driver is executed to render the printer specific
+output.</p></li></ul></div><p>
+Both print paths are shown in the flowcharts below.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958155"></a>Driver Execution on the Client</h3></div></div><div></div></div><p>
+In the first case the print server must spool the file as &quot;raw&quot;,
+meaning it shouldn't touch the jobfile and try to convert it in any
+way. This is what traditional Unix-based print server can do too; and
+at a better performance and more reliably than NT print server. This
+is what most Samba administrators probably are familiar with. One
+advantage of this setup is that this &quot;spooling-only&quot; print server may
+be used even if no driver(s) for Unix are available it is sufficient
+to have the Windows client drivers available and installed on the
+clients.
+</p><p>
+</p><div class="figure"><a name="id2958191"></a><p class="title"><b>Figure 19.11. Print Driver execution on the Client</b></p><div class="mediaobject"><img src="projdoc/imagefiles/11small.png" alt="Print Driver execution on the Client"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958227"></a>Driver Execution on the Server</h3></div></div><div></div></div><p>
+The other path executes the printer driver on the server. The clients
+transfers print files in EMF format to the server. The server uses the
+PostScript, PCL, ESC/P or other driver to convert the EMF file into
+the printer-specific language. It is not possible for Unix to do the
+same. Currently there is no program or method to convert a Windows
+client's GDI output on a Unix server into something a printer could
+understand.
+</p><p>
+</p><div class="figure"><a name="id2958249"></a><p class="title"><b>Figure 19.12. Print Driver execution on the Server</b></p><div class="mediaobject"><img src="projdoc/imagefiles/12small.png" alt="Print Driver execution on the Server"></div></div><p>
+</p><p>
+However, there is something similar possible with CUPS. Read on...
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2958289"></a>Network Printing (Windows clients -- UNIX/Samba Print
+Servers)</h2></div></div><div></div></div><p>
+Since UNIX print servers <span class="emphasis"><em>cannot</em></span> execute the Win32
+program code on their platform, the picture is somewhat
+different. However, this doesn't limit your options all that
+much. In the contrary, you may have a way here to implement printing
+features which are not possible otherwise.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958310"></a>From Windows Clients to a CUPS/Samba Print Server</h3></div></div><div></div></div><p>
+Here is a simple recipe showing how you can take advantage of CUPS
+powerful features for the benefit of your Windows network printing
+clients:
+</p><div class="itemizedlist"><ul type="disc"><li><p>Let the Windows clients send PostScript to the CUPS
+server.</p></li><li><p>Let the CUPS server render the PostScript into device
+specific raster format.</p></li></ul></div><p>
+This requires the clients to use a PostScript driver (even if the
+printer is a non-PostScript model. It also requires that you have a
+&quot;driver&quot; on the CUPS server.
+</p><p>
+Firstly, to enable CUPS based printing through Samba the
+following options should be set in your <tt class="filename">smb.conf</tt> file [globals]
+section:
+</p><div class="itemizedlist"><ul type="disc"><li><p><i class="parameter"><tt>printing = CUPS</tt></i></p></li><li><p><i class="parameter"><tt>printcap = CUPS</tt></i></p></li></ul></div><p>
+When these parameters are specified, all manually set print directives
+(like <i class="parameter"><tt>print command =...</tt></i>, or <i class="parameter"><tt>lppause
+command =...</tt></i>) in <tt class="filename">smb.conf</tt> (as well as
+in samba itself) will be ignored. Instead, Samba will directly
+interface with CUPS through it's application program interface (API) -
+as long as Samba has been compiled with CUPS library (libcups)
+support. If Samba has NOT been compiled with CUPS support, and if no
+other print commands are set up, then printing will use the
+<span class="emphasis"><em>System V</em></span> AT&amp;T command set, with the -oraw
+option automatically passing through (if you want your own defined
+print commands to work with a Samba that has CUPS support compiled in,
+simply use <i class="parameter"><tt>printing = sysv</tt></i>).
+</p><p>
+</p><div class="figure"><a name="id2958439"></a><p class="title"><b>Figure 19.13. Printing via CUPS/samba server</b></p><div class="mediaobject"><img src="projdoc/imagefiles/13small.png" alt="Printing via CUPS/samba server"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958474"></a>Samba receiving Jobfiles and passing them to CUPS</h3></div></div><div></div></div><p>
+Samba <span class="emphasis"><em>must</em></span> use its own spool directory (it is set
+by a line similar to <i class="parameter"><tt>path = /var/spool/samba</tt></i>,
+in the <i class="parameter"><tt>[printers]</tt></i> or
+<i class="parameter"><tt>[printername]</tt></i> section of
+<tt class="filename">smb.conf</tt>). Samba receives the job in its own
+spool space and passes it into the spool directory of CUPS (the CUPS
+spooling directory is set by the <i class="parameter"><tt>RequestRoot</tt></i>
+directive, in a line that defaults to <i class="parameter"><tt>RequestRoot
+/var/spool/cups</tt></i>).  CUPS checks the access rights of its
+spool dir and resets it to healthy values with every re-start. We have
+seen quite some people who had used a common spooling space for Samba
+and CUPS, and were struggling for weeks with this &quot;problem&quot;.
+</p><p>
+A Windows user authenticates only to Samba (by whatever means is
+configured). If Samba runs on the same host as CUPS, you only need to
+allow &quot;localhost&quot; to print. If they run on different machines, you
+need to make sure the Samba host gets access to printing on CUPS.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2958550"></a>Network PostScript RIP: CUPS Filters on Server -- clients use
+PostScript Driver with CUPS-PPDs</h2></div></div><div></div></div><p>
+PPDs can control all print device options. They are usually provided
+by the manufacturer; if you own a PostScript printer, that is. PPD
+files (PostScript Printer Descriptions) are always a component of
+PostScript printer drivers on MS Windows or Apple Mac OS systems. They
+are ASCII files containing user-selectable print options, mapped to
+appropriate PostScript, PCL or PJL commands for the target
+printer. Printer driver GUI dialogs translate these options
+&quot;on-the-fly&quot; into buttons and drop-down lists for the user to select.
+</p><p>
+CUPS can load, without any conversions, the PPD file from any Windows
+(NT is recommended) PostScript driver and handle the options. There is
+a web browser interface to the print options (select <a href="http://localhost:631/printers/" target="_top">http://localhost:631/printers/</a>
+and click on one <span class="emphasis"><em>Configure Printer</em></span> button to see
+it), or a commandline interface (see <b class="command">man lpoptions</b>
+or see if you have lphelp on your system). There are also some
+different GUI frontends on Linux/UNIX, which can present PPD options
+to users. PPD options are normally meant to be evaluated by the
+PostScript RIP on the real PostScript printer.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958605"></a>PPDs for non-PS Printers on UNIX</h3></div></div><div></div></div><p>
+CUPS doesn't limit itself to &quot;real&quot; PostScript printers in its usage
+of PPDs. The CUPS developers have extended the scope of the PPD
+concept, to also describe available device and driver options for
+non-PostScript printers through CUPS-PPDs.
+</p><p>
+This is logical, as CUPS includes a fully featured PostScript
+interpreter (RIP). This RIP is based on Ghostscript. It can process
+all received PostScript (and additionally many other file formats)
+from clients. All CUPS-PPDs geared to non-PostScript printers contain
+an additional line, starting with the keyword
+<i class="parameter"><tt>*cupsFilter</tt></i> . This line tells the CUPS print
+system which printer-specific filter to use for the interpretation of
+the supplied PostScript. Thus CUPS lets all its printers appear as
+PostScript devices to its clients, because it can act as a PostScript
+RIP for those printers, processing the received PostScript code into a
+proper raster print format.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958646"></a>PPDs for non-PS Printers on Windows</h3></div></div><div></div></div><p>
+CUPS-PPDs can also be used on Windows-Clients, on top of a
+&quot;core&quot; PostScript driver (now recommended is the &quot;CUPS PostScript
+Driver for WindowsNT/2K/XP&quot;; you can also use the Adobe one, with
+limitations). This feature enables CUPS to do a few tricks no other
+spooler can do:
+</p><div class="itemizedlist"><ul type="disc"><li><p>act as a networked PostScript RIP (Raster Image
+Processor), handling printfiles from all client platforms in a uniform
+way;</p></li><li><p>act as a central accounting and billing server, since
+all files are passed through the pstops filter and are therefore
+logged in the CUPS <tt class="filename">page_log</tt> file.
+<span class="emphasis"><em>NOTE:</em></span> this can not happen with &quot;raw&quot; print jobs,
+which always remain unfiltered per definition;</p></li><li><p>enable clients to consolidate on a single PostScript
+driver, even for many different target printers.</p></li></ul></div><p>
+Using CUPS PPDs on Windows clients enables these to control
+all print job settings just as a UNIX client can do too.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2958712"></a>Windows Terminal Servers (WTS) as CUPS Clients</h2></div></div><div></div></div><p>
+This setup may be of special interest to people experiencing major
+problems in WTS environments. WTS need often a multitude of
+non-PostScript drivers installed to run their clients' variety of
+different printer models. This often imposes the price of much
+increased instability.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958729"></a>Printer Drivers running in &quot;Kernel Mode&quot; cause many
+Problems</h3></div></div><div></div></div><p>
+The reason is that in Win NT printer drivers run in &quot;Kernel
+Mode&quot;, this introduces a high risk for the stability of the system
+if the driver is not really stable and well-tested. And there are a
+lot of bad drivers out there! Especially notorious is the example
+of the PCL printer driver that had an additional sound module
+running, to notify users via soundcard of their finished jobs. Do I
+need to say that this one was also reliably causing &quot;Blue Screens
+of Death&quot; on a regular basis?
+</p><p>
+PostScript drivers generally are very well tested. They are not known
+to cause any problems, even though they run in Kernel Mode too. This
+might be because there have so far only been 2 different PostScript
+drivers the ones from Adobe and the one from Microsoft. Both are
+very well tested and are as stable as you ever can imagine on
+Windows. The CUPS driver is derived from the Microsoft one.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958763"></a>Workarounds impose Heavy Limitations</h3></div></div><div></div></div><p>
+In many cases, in an attempt to work around this problem, site
+administrators have resorted to restrict the allowed drivers installed
+on their WTS to one generic PCL- and one PostScript driver. This
+however restricts the clients in the amount of printer options
+available for them; often they can't get out more than simplex
+prints from one standard paper tray, while their devices could do much
+better, if driven by a different driver! )
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958784"></a>CUPS: a &quot;Magical Stone&quot;?</h3></div></div><div></div></div><p>
+Using a PostScript driver, enabled with a CUPS-PPD, seems to be a very
+elegant way to overcome all these shortcomings. There are, depending
+on the version of Windows OS you use, up to 3 different PostScript
+drivers available: Adobe, Microsoft and CUPS PostScript drivers. None
+of them is known to cause major stability problems on WTS (even if
+used with many different PPDs). The clients will be able to (again)
+chose paper trays, duplex printing and other settings. However, there
+is a certain price for this too: a CUPS server acting as a PostScript
+RIP for its clients requires more CPU and RAM than when just acting as
+a &quot;raw spooling&quot; device.  Plus, this setup is not yet widely tested,
+although the first feedbacks look very promising.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958811"></a>PostScript Drivers with no major problems -- even in Kernel
+Mode</h3></div></div><div></div></div><p>
+More recent printer drivers on W2K and XP don't run in Kernel mode
+(unlike Win NT) any more. However, both operating systems can still
+use the NT drivers, running in Kernel mode (you can roughly tell which
+is which as the drivers in subdirectory &quot;2&quot; of &quot;W32X86&quot; are &quot;old&quot;
+ones).  As was said before, the Adobe as well as the Microsoft
+PostScript drivers are not known to cause any stability problems. The
+CUPS driver is derived from the Microsoft one. There is a simple
+reason for this: The MS DDK (Device Development Kit) for Win NT (which
+used to be available at no cost to licensees of Visual Studio)
+includes the source code of the Microsoft driver, and licensees of
+Visual Studio are allowed to use and modify it for their own driver
+development efforts. This is what the CUPS people have done. The
+license doesn't allow them to publish the whole of the source code.
+However, they have released the &quot;diff&quot; under the GPL, and if you are
+owner of an &quot;MS DDK for Win NT&quot;, you can check the driver yourself.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2958865"></a> Setting up CUPS for driver Download</h2></div></div><div></div></div><p>
+As we have said before: all previously known methods to prepare client
+printer drivers on the Samba server for download and &quot;Point'n'Print&quot;
+convenience of Windows workstations are working with CUPS too. These
+methods were described in the previous chapter. In reality, this is a
+pure Samba business, and only relates to the Samba/Win client
+relationship.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958884"></a><span class="emphasis"><em>cupsaddsmb</em></span>: the unknown Utility</h3></div></div><div></div></div><p>
+The cupsaddsmb utility (shipped with all current CUPS versions) is an
+alternative method to transfer printer drivers into the Samba
+<i class="parameter"><tt>[print$]</tt></i> share. Remember, this share is where
+clients expect drivers deposited and setup for download and
+installation.  It makes the sharing of any (or all) installed CUPS
+printers very easy. cupsaddsmb can use the Adobe PostScript driver as
+well as the newly developed <span class="emphasis"><em>CUPS PostScript Driver for
+WinNT/2K/XP</em></span>. Note, that cupsaddsmb does
+<span class="emphasis"><em>not</em></span> work with arbitrary vendor printer drivers,
+but only with the <span class="emphasis"><em>exact</em></span> driver files that are
+named in its man page.
+</p><p>
+The CUPS printer driver is available from the CUPS download site. Its
+package name is <tt class="filename">cups-samba-[version].tar.gz</tt> . It
+is preferred over the Adobe drivers since it has a number of
+advantages:
+</p><div class="itemizedlist"><ul type="disc"><li><p>it supports a much more accurate page
+accounting;</p></li><li><p>it supports banner pages, and page labels on all
+printers;</p></li><li><p>it supports the setting of a number of job IPP
+attributes (such as job-priority, page-label and
+job-billing)</p></li></ul></div><p>
+However, currently only Windows NT, 2000, and XP are supported by the
+CUPS drivers. You will need to get the respective part of Adobe driver
+too if you need to support Windows 95, 98, and ME clients.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2958976"></a>Prepare your <tt class="filename">smb.conf</tt> for
+cupsaddsmb</h3></div></div><div></div></div><p>
+Prior to running cupsaddsmb, you need the following settings in
+<tt class="filename">smb.conf</tt>:
+</p><pre class="screen">
+
+ [global]
+         load printers = yes
+         printing = cups
+         printcap name = cups
+
+ [printers]
+         comment = All Printers
+         path = /var/spool/samba
+         browseable = no
+         public = yes
+         guest ok = yes           # setting depends on your requirements
+         writable = no
+         printable = yes
+         printer admin = root
+
+ [print$]
+         comment = Printer Drivers
+         path = /etc/samba/drivers
+         browseable = yes
+         guest ok = no
+         read only = yes
+         write list = root  
+
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959022"></a>CUPS Package of &quot;PostScript Driver for WinNT/2k/XP&quot;</h3></div></div><div></div></div><p>
+CUPS users may get the exactly same packages from<a href="http://www.cups.org/software.html" target="_top"><span class="emphasis"><em>http://www.cups.org/software.html</em></span></a>.
+It is a separate package from the CUPS base software files, tagged as
+<span class="emphasis"><em>CUPS 1.1.x Windows NT/2k/XP Printer Driver for SAMBA
+(tar.gz, 192k)</em></span>. The filename to download is
+<tt class="filename">cups-samba-1.1.x.tar.gz</tt>. Upon untar-/unzip-ing,
+it will reveal these files:
+</p><pre class="screen">
+
+# tar xvzf cups-samba-1.1.19.tar.gz 
+
+   cups-samba.install
+   cups-samba.license
+   cups-samba.readme
+   cups-samba.remove
+   cups-samba.ss
+
+</pre><p>
+These have been packaged with the ESP meta packager software
+&quot;EPM&quot;. The <tt class="filename">*.install</tt> and
+<tt class="filename">*.remove</tt> files are simple shell scripts, which
+untars the <tt class="filename">*.ss</tt> (the <tt class="filename">*.ss</tt> is
+nothing else but a tar-archive, which can be untar-ed by &quot;tar&quot;
+too). Then it puts the content into
+<tt class="filename">/usr/share/cups/drivers/</tt>. This content includes 3
+files:
+</p><pre class="screen">
+
+# tar tv cups-samba.ss
+
+    cupsdrvr.dll
+    cupsui.dll
+    cups.hlp  
+
+</pre><p>
+The <span class="emphasis"><em>cups-samba.install</em></span> shell scripts is easy to
+handle:
+</p><pre class="screen">
+
+# ./cups-samba.install
+
+   [....]
+   Installing software...
+   Updating file permissions...
+   Running post-install commands...
+   Installation is complete.        
+
+</pre><p>
+The script should automatically put the driver files into the
+<tt class="filename">/usr/share/cups/drivers/</tt> directory.
+</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+Due to a bug, one recent CUPS release puts the
+<tt class="filename">cups.hlp</tt> driver file
+into<tt class="filename">/usr/share/drivers/</tt> instead of
+<tt class="filename">/usr/share/cups/drivers/</tt>. To work around this,
+copy/move the file (after running the
+<b class="command">./cups-samba.install</b> script) manually to the
+right place.
+</p></div><pre class="screen">
+
+   cp /usr/share/drivers/cups.hlp /usr/share/cups/drivers/
+
+</pre><p>
+This new CUPS PostScript driver is currently binary-only, but free of
+charge. No complete source code is provided (yet). The reason is this:
+it has been developed with the help of the <span class="emphasis"><em>Microsoft Driver
+Developer Kit</em></span> (DDK) and compiled with Microsoft Visual
+Studio 6. Driver developers are not allowed to distribute the whole of
+the source code as Free Software. However, CUPS developers released
+the &quot;diff&quot; 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.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959220"></a>Recognize the different Driver Files</h3></div></div><div></div></div><p>
+The CUPS drivers don't support the &quot;older&quot; Windows 95/98/ME, but only
+the Windows NT/2000/XP client:
+</p><pre class="screen">
+
+ [Windows NT, 2000, and XP are supported by:]
+         cups.hlp
+         cupsdrvr.dll
+         cupsui.dll
+
+</pre><p>
+Adobe drivers are available for the older Windows 95/98/ME as well as
+the Windows NT/2000/XP clients. The set of files is different for the
+different platforms.
+</p><pre class="screen">
+
+ [Windows 95, 98, and Me are supported by:]
+         ADFONTS.MFM
+         ADOBEPS4.DRV
+         ADOBEPS4.HLP
+         DEFPRTR2.PPD
+         ICONLIB.DLL
+         PSMON.DLL
+
+ [Windows NT, 2000, and XP are supported by:]
+         ADOBEPS5.DLL
+         ADOBEPSU.DLL
+         ADOBEPSU.HLP
+
+</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+If both, the Adobe driver files and the CUPS driver files for the
+support of WinNT/2k/XP are present in , the Adobe ones will be ignored
+and the CUPS ones will be used. If you prefer -- for whatever reason
+-- to use Adobe-only drivers, move away the 3 CUPS driver files. The
+Win95/98/ME clients use the Adobe drivers in any case.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959278"></a>Acquiring the Adobe Driver Files</h3></div></div><div></div></div><p>
+Acquiring the Adobe driver files seems to be unexpectedly difficult
+for many users. They are not available on the Adobe website as single
+files and the self-extracting and/or self-installing Windows-exe is
+not easy to locate either. Probably you need to use the included
+native installer and run the installation process on one client
+once. This will install the drivers (and one Generic PostScript
+printer) locally on the client.  When they are installed, share the
+Generic PostScript printer.  After this, the client's
+<i class="parameter"><tt>[print$]</tt></i> share holds the Adobe files, from
+where you can get them with smbclient from the CUPS host. A more
+detailed description about this is in the next (the CUPS printing)
+chapter.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959310"></a>ESP Print Pro Package of &quot;PostScript Driver for
+WinNT/2k/XP&quot;</h3></div></div><div></div></div><p>
+Users of the ESP Print Pro software are able to install their &quot;Samba
+Drivers&quot; package for this purpose with no problem. Retrieve the driver
+files from the normal download area of the ESP Print Pro software
+at<a href="http://www.easysw.com/software.html" target="_top">http://www.easysw.com/software.html</a>.
+You need to locate the link labelled &quot;SAMBA&quot; amongst the
+<span class="emphasis"><em>Download Printer Drivers for ESP Print Pro 4.x</em></span>
+area and download the package. Once installed, you can prepare any
+driver by simply highlighting the printer in the Printer Manager GUI
+and select <span class="emphasis"><em>Export Driver...</em></span> from the menu. Of
+course you need to have prepared Samba beforehand too to handle the
+driver files; i.e.  mainly setup the <i class="parameter"><tt>[print$]</tt></i>
+share, etc. The ESP Print Pro package includes the CUPS driver files
+as well as a (licensed) set of Adobe drivers for the Windows 95/98/ME
+client family.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959360"></a>Caveats to be considered</h3></div></div><div></div></div><p>
+Once you have run the install script (and possibly manually
+moved the <tt class="filename">cups.hlp</tt> file to
+<tt class="filename">/usr/share/cups/drivers/</tt>), the driver is
+ready to be put into Samba's <i class="parameter"><tt>[print$]</tt></i> share (which often maps to
+<tt class="filename">/etc/samba/drivers/</tt> and contains a subdir
+tree with <span class="emphasis"><em>WIN40</em></span> and
+<span class="emphasis"><em>W32X86</em></span> branches): You do this by running
+&quot;cupsaddsmb&quot; (see also <b class="command">man cupsaddsmb</b> for
+CUPS since release 1.1.16).
+</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
+You may need to put root into the smbpasswd file by running
+<b class="command">smbpasswd</b>; this is especially important if you
+should run this whole procedure for the first time, and are not
+working in an environment where everything is configured for
+<span class="emphasis"><em>Single Sign On</em></span> to a Windows Domain Controller.
+</p></div><p>
+Once the driver files are in the <i class="parameter"><tt>[print$]</tt></i> share
+and are initialized, they are ready to be downloaded and installed by
+the Win NT/2k/XP clients.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+</p><div class="orderedlist"><ol type="1"><li><p>
+Win 9x/ME clients won't work with the CUPS PostScript driver. For
+these you'd still need to use the <tt class="filename">ADOBE*.*</tt>
+drivers as previously.
+</p></li><li><p>
+It is not harmful if you still have the
+<tt class="filename">ADOBE*.*</tt> driver files from previous
+installations in the <tt class="filename">/usr/share/cups/drivers/</tt>
+directory. The new <span class="emphasis"><em>cupsaddsmb</em></span> (from 1.1.16) will
+automatically prefer &quot;its own&quot; drivers if it finds both.
+</p></li><li><p>
+Should your Win clients have had the old <tt class="filename">ADOBE*.*</tt>
+files for the Adobe PostScript driver installed, the download and
+installation of the new CUPS PostScript driver for Windows NT/2k/XP
+will fail at first. You need to wipe the old driver from the clients
+first. It is not enough to &quot;delete&quot; 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 &quot;Printers&quot; folder (possibly via <span class="emphasis"><em>Start
+--&gt; Settings --&gt; Control Panel --&gt; Printers</em></span>),
+right-click onto the folder background and select <span class="emphasis"><em>Server
+Properties</em></span>. When the new dialog opens, select the
+<span class="emphasis"><em>Drivers</em></span> tab. On the list select the driver you
+want to delete and click on the <span class="emphasis"><em>Delete</em></span>
+button. This will only work if there is not one single printer left
+which uses that particular driver. You need to &quot;delete&quot; all printers
+using this driver in the &quot;Printers&quot; folder first. You will need
+Administrator privileges to do this.
+</p></li><li><p>
+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 &quot;Samba HOWTO Collection&quot;: either change
+a driver for an existing printer by running the &quot;Printer Properties&quot;
+dialog, or use <b class="command">rpcclient</b> with the
+<b class="command">setdriver</b> sub-command.
+</p></li></ol></div><p>
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959582"></a>What are the Benefits of using the &quot;CUPS PostScript Driver for
+Windows NT/2k/XP&quot; as compared to the Adobe Driver?</h3></div></div><div></div></div><p>
+You are interested in a comparison between the CUPS and the Adobe
+PostScript drivers? For our purposes these are the most important
+items which weigh in favor of the CUPS ones:
+</p><div class="itemizedlist"><ul type="disc"><li><p>no hassle with the Adobe EULA</p></li><li><p>no hassle with the question &#8220;<span class="quote">Where do I
+get the ADOBE*.* driver files from?</span>&#8221;</p></li><li><p>the Adobe drivers (on request of the printer PPD
+associated with them) often put a PJL header in front of the main
+PostScript part of the print file. Thus the printfile starts with
+<i class="parameter"><tt>&lt;1B &gt;%-12345X</tt></i> or
+<i class="parameter"><tt>&lt;escape&gt;%-12345X</tt></i> instead
+of <i class="parameter"><tt>%!PS</tt></i>). This leads to the
+CUPS daemon auto-typing the incoming file as a print-ready file,
+not initiating a pass through the &quot;pstops&quot; filter (to speak more
+technically, it is not regarded as the generic MIME type 
+<span class="emphasis"><em>application/postscript</em></span>, but as
+the more special MIME type
+<span class="emphasis"><em>application/cups.vnd-postscript</em></span>),
+which therefore also leads to the page accounting in
+<span class="emphasis"><em>/var/log/cups/page_log</em></span> not
+receiving the exact number of pages; instead the dummy page number
+of &quot;1&quot; is logged in a standard setup)</p></li><li><p>the Adobe driver has more options to &quot;mis-configure&quot; the
+PostScript generated by it (like setting it inadvertently to
+<span class="emphasis"><em>Optimize for Speed</em></span>, instead of
+<span class="emphasis"><em>Optimize for Portability</em></span>, which
+could lead to CUPS being unable to process it)</p></li><li><p>the CUPS PostScript driver output sent by Windows
+clients to the CUPS server will be guaranteed to be auto-typed always
+as generic MIME type <span class="emphasis"><em>application/postscript</em></span>,
+thusly passing through the CUPS &quot;pstops&quot; filter and logging the
+correct number of pages in the <tt class="filename">page_log</tt> for
+accounting and quota purposes</p></li><li><p>the CUPS PostScript driver supports the sending of
+additional standard (IPP) print options by Win NT/2k/XP clients.  Such
+additional print options are: naming the CUPS standard
+<span class="emphasis"><em>banner pages</em></span> (or the custom ones, should they be
+installed at the time of driver download), using the CUPS
+<span class="emphasis"><em>page-label</em></span> option, setting a
+<span class="emphasis"><em>job-priority</em></span> and setting the <span class="emphasis"><em>scheduled
+time of printing</em></span> (with the option to support additional
+useful IPP job attributes in the future).</p></li><li><p>the CUPS PostScript driver supports the inclusion of
+the new <span class="emphasis"><em>*cupsJobTicket</em></span> comments at the
+beginning 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 applications as they will regard it as a comment
+and simply ignore it).</p></li><li><p>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).</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959764"></a>Run &quot;cupsaddsmb&quot; (quiet Mode)</h3></div></div><div></div></div><p>
+The cupsaddsmb command copies the needed files into your
+<i class="parameter"><tt>[print$]</tt></i> share. Additionally, the PPD
+associated with this printer is copied from
+<tt class="filename">/etc/cups/ppd/</tt> to
+<i class="parameter"><tt>[print$]</tt></i>. There the files wait for convenient
+Windows client installations via Point'n'Print. Before we can run the
+command successfully, we need to be sure that we can authenticate
+towards Samba. If you have a small network you are probably using user
+level security (<i class="parameter"><tt>security = user</tt></i>). Probably your
+root has already a Samba account. Otherwise, create it now, using
+<b class="command">smbpasswd</b>:
+</p><pre class="screen">
+
+ #  smbpasswd -a root 
+ New SMB password: [type in password 'secret']
+ Retype new SMB password: [type in password 'secret']
+
+</pre><p>
+Here is an example of a successfully run cupsaddsmb command. 
+</p><pre class="screen">
+
+ #  cupsaddsmb -U root infotec_IS2027
+ Password for root required to access localhost via SAMBA: [type in password 'secret']
+
+</pre><p>
+To share <span class="emphasis"><em>all</em></span> printers and drivers, use the
+<i class="parameter"><tt>-a</tt></i> parameter instead of a printer name. Since
+cupsaddsmb &quot;exports&quot; the printer drivers to Samba, it should be
+obvious that it only works for queues with a CUPS driver associated.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2959865"></a>Run &quot;cupsaddsmb&quot; with verbose Output</h3></div></div><div></div></div><p>
+Probably you want to see what's going on. Use the
+<i class="parameter"><tt>-v</tt></i> parameter to get a more verbose output. The
+output below was edited for better readability: all &quot;\&quot; at the end of
+a line indicate that I inserted an artificial line break plus some
+indentation here:
+</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
+You will see the root password for the Samba account printed on
+screen. If you use remote access, the password will go over the wire
+unencrypted!
+</p></div><pre class="screen">
+
+  # cupsaddsmb -U root -v infotec_2105
+  Password for root required to access localhost via SAMBA:
+  Running command: smbclient //localhost/print\$ -N -U'root%secret' -c 'mkdir W32X86;put   \
+                   /var/spool/cups/tmp/3e98bf2d333b5 W32X86/infotec_2105.ppd;put           \
+                   /usr/share/cups/drivers/cupsdrvr.dll W32X86/cupsdrvr.dll;put            \
+                   /usr/share/cups/drivers/cupsui.dll W32X86/cupsui.dll;put                \
+                   /usr/share/cups/drivers/cups.hlp W32X86/cups.hlp'
+  added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
+  Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
+  NT_STATUS_OBJECT_NAME_COLLISION making remote directory \W32X86
+  putting file /var/spool/cups/tmp/3e98bf2d333b5 as \W32X86/infotec_2105.ppd (2328.8 kb/s) \
+               (average 2328.8 kb/s)
+  putting file /usr/share/cups/drivers/cupsdrvr.dll as \W32X86/cupsdrvr.dll (9374.3 kb/s)  \
+               (average 5206.6 kb/s)
+  putting file /usr/share/cups/drivers/cupsui.dll as \W32X86/cupsui.dll (8107.2 kb/s)      \
+               (average 5984.1 kb/s)
+  putting file /usr/share/cups/drivers/cups.hlp as \W32X86/cups.hlp (3475.0 kb/s)          \
+               (average 5884.7 kb/s)
+  
+  Running command: rpcclient localhost -N -U'root%secret' -c 'adddriver &quot;Windows NT x86&quot;   \
+                   &quot;infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll:cups.hlp:NULL:   \
+                   RAW:NULL&quot;'
+  cmd = adddriver &quot;Windows NT x86&quot; &quot;infotec_2105:cupsdrvr.dll:infotec_2105.ppd:cupsui.dll: \
+                   cups.hlp:NULL:RAW:NULL&quot;
+  Printer Driver infotec_2105 successfully installed.
+  
+  Running command: smbclient //localhost/print\$ -N -U'root%secret' -c 'mkdir WIN40;put    \
+                   /var/spool/cups/tmp/3e98bf2d333b5 WIN40/infotec_2105.PPD; put           \
+                   /usr/share/cups/drivers/ADFONTS.MFM WIN40/ADFONTS.MFM;put               \
+                   /usr/share/cups/drivers/ADOBEPS4.DRV WIN40/ADOBEPS4.DRV;put             \
+                   /usr/share/cups/drivers/ADOBEPS4.HLP WIN40/ADOBEPS4.HLP;put             \
+                   /usr/share/cups/drivers/DEFPRTR2.PPD WIN40/DEFPRTR2.PPD;put             \
+                   /usr/share/cups/drivers/ICONLIB.DLL
+  WIN40/ICONLIB.DLL;put /usr/share/cups/drivers/PSMON.DLL WIN40/PSMON.DLL;'
+  added interface ip=10.160.51.60 bcast=10.160.51.255 nmask=255.255.252.0
+  Domain=[CUPS-PRINT] OS=[Unix] Server=[Samba 2.2.7a]
+  NT_STATUS_OBJECT_NAME_COLLISION making remote directory \WIN40
+  putting file /var/spool/cups/tmp/3e98bf2d333b5 as \WIN40/infotec_2105.PPD (2328.8 kb/s)  \
+               (average 2328.8 kb/s)
+  putting file /usr/share/cups/drivers/ADFONTS.MFM as \WIN40/ADFONTS.MFM (9368.0 kb/s)     \
+               (average 6469.6 kb/s)
+  putting file /usr/share/cups/drivers/ADOBEPS4.DRV as \WIN40/ADOBEPS4.DRV (9958.2 kb/s)   \
+               (average 8404.3 kb/s)
+  putting file /usr/share/cups/drivers/ADOBEPS4.HLP as \WIN40/ADOBEPS4.HLP (8341.5 kb/s)   \
+               (average 8398.6 kb/s)
+  putting file /usr/share/cups/drivers/DEFPRTR2.PPD as \WIN40/DEFPRTR2.PPD (2195.9 kb/s)   \
+               (average 8254.3 kb/s)
+  putting file /usr/share/cups/drivers/ICONLIB.DLL as \WIN40/ICONLIB.DLL (8239.9 kb/s)     \
+               (average 8253.6 kb/s)
+  putting file /usr/share/cups/drivers/PSMON.DLL as \WIN40/PSMON.DLL (6222.2 kb/s)         \
+               (average 8188.5 kb/s)
+  
+  Running command: rpcclient localhost -N -U'root%secret' -c 'adddriver &quot;Windows 4.0&quot;      \
+                   &quot;infotec_2105:ADOBEPS4.DRV:infotec_2105.PPD:NULL:ADOBEPS4.HLP:          \
+                   PSMON.DLL:RAW:ADOBEPS4.DRV,infotec_2105.PPD,ADOBEPS4.HLP,PSMON.DLL,     \
+                   ADFONTS.MFM,DEFPRTR2.PPD,ICONLIB.DLL&quot;'
+  cmd = adddriver &quot;Windows 4.0&quot; &quot;infotec_2105:ADOBEPS4.DRV:infotec_2105.PPD:NULL:          \
+                   ADOBEPS4.HLP:PSMON.DLL:RAW:ADOBEPS4.DRV,infotec_2105.PPD,ADOBEPS4.HLP,  \
+                   PSMON.DLL,ADFONTS.MFM,DEFPRTR2.PPD,ICONLIB.DLL&quot;
+  Printer Driver infotec_2105 successfully installed.
+  
+  Running command: rpcclient localhost -N -U'root%secret'                                  \
+                             -c 'setdriver infotec_2105 infotec_2105'
+  cmd = setdriver infotec_2105 infotec_2105
+  Successfully set infotec_2105 to driver infotec_2105.
+
+</pre><p>
+If you look closely, you'll discover your root password was transfered
+unencrypted over the wire, so beware! Also, if you look further her,
+you'll discover error messages like NT_STATUS_OBJECT_NAME_COLLISION in
+between. They occur, because the directories WIN40 and W32X86 already
+existed in the <i class="parameter"><tt>[print$]</tt></i> driver download share
+(from a previous driver installation). They are harmless here.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960092"></a>Understanding cupsaddsmb</h3></div></div><div></div></div><p>
+What has happened? What did cupsaddsmb do? There are five stages of
+the procedure
+</p><div class="orderedlist"><ol type="1"><li><p>call the CUPS server via IPP and request the
+driver files and the PPD file for the named printer;</p></li><li><p>store the files temporarily in the local
+TEMPDIR (as defined in
+<tt class="filename">cupsd.conf</tt>);</p></li><li><p>connect via smbclient to the Samba server's
+ <i class="parameter"><tt>[print$]</tt></i> share and put the files into the
+ share's WIN40 (for Win95/98/ME) and W32X86/ (for WinNT/2k/XP) sub
+ directories;</p></li><li><p>connect via rpcclient to the Samba server and
+execute the &quot;adddriver&quot; command with the correct
+parameters;</p></li><li><p>connect via rpcclient to the Samba server a second
+time and execute the &quot;setdriver&quot; command.</p></li></ol></div><p>
+Note, that you can run the cupsaddsmb utility with parameters to
+specify one remote host as Samba host and a second remote host as CUPS
+host. Especially if you want to get a deeper understanding, it is a
+good idea try it and see more clearly what is going on (though in real
+life most people will have their CUPS and Samba servers run on the
+same host):
+</p><pre class="screen">
+
+ # cupsaddsmb -H sambaserver -h cupsserver -v printername
+
+</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960186"></a>How to recognize if cupsaddsm completed successfully</h3></div></div><div></div></div><p>
+You <span class="emphasis"><em>must</em></span> always check if the utility completed
+successfully in all fields. You need as a minimum these 3 messages
+amongst the output:
+</p><div class="orderedlist"><ol type="1"><li><p><span class="emphasis"><em>Printer Driver infotec_2105 successfully
+installed.</em></span> # (for the W32X86 == WinNT/2K/XP
+architecture...)</p></li><li><p><span class="emphasis"><em>Printer Driver infotec_2105 successfully
+installed.</em></span> # (for the WIN40 == Win9x/ME
+architecture...)</p></li><li><p><span class="emphasis"><em>Successfully set [printerXPZ] to driver
+[printerXYZ].</em></span></p></li></ol></div><p>
+These messages probably not easily recognized in the general
+output. If you run cupsaddsmb with the <i class="parameter"><tt>-a</tt></i>
+parameter (which tries to prepare <span class="emphasis"><em>all</em></span> active CUPS
+printer drivers for download), you might miss if individual printers
+drivers had problems to install properly. Here a redirection of the
+output will help you analyze the results in retrospective.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+It is impossible to see any diagnostic output if you don't run
+cupsaddsmb in verbose mode.  Therefore we strongly recommend to not
+use the default quiet mode.  It will hide any problems from you which
+might occur.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960273"></a>cupsaddsmb with a Samba PDC</h3></div></div><div></div></div><p>
+You can't get the standard cupsaddsmb command to run on a Samba PDC?
+You are asked for the password credential all over again and again and
+the command just will not take off at all? Try one of these
+variations:
+</p><pre class="screen">
+
+ # cupsaddsmb -U DOMAINNAME\\root -v printername
+ # cupsaddsmb -H SAMBA-PDC -U DOMAINNAME\\root -v printername
+ # cupsaddsmb -H SAMBA-PDC -U DOMAINNAME\\root -h cups-server -v printername
+
+</pre><p>
+(Note the two backslashes: the first one is required to
+&quot;escape&quot; the second one).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960308"></a>cupsaddsmb Flowchart</h3></div></div><div></div></div><p>
+Here is a chart about the procedures, commandflows and
+dataflows of the &quot;cupaddsmb&quot; command. Note again: cupsaddsmb is
+not intended to, and does not work with, &quot;raw&quot; queues!
+</p><p>
+</p><div class="figure"><a name="id2960326"></a><p class="title"><b>Figure 19.14. cupsaddsmb flowchart</b></p><div class="mediaobject"><img src="projdoc/imagefiles/1small.png" alt="cupsaddsmb flowchart"></div></div><p>
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960361"></a>Installing the PostScript Driver on a Client</h3></div></div><div></div></div><p>
+After cupsaddsmb completed, your driver is prepared for the clients to
+use. Here are the steps you must perform to download and install it
+via &quot;Point'n'Print&quot;. From a Windows client, browse to the CUPS/Samba
+server;
+</p><div class="itemizedlist"><ul type="disc"><li><p>open the <span class="emphasis"><em>Printers</em></span>
+share of Samba in Network Neighbourhood;</p></li><li><p>right-click on the printer in
+question;</p></li><li><p>from the opening context-menu select
+<span class="emphasis"><em>Install...</em></span> or 
+<span class="emphasis"><em>Connect...</em></span> (depending on the Windows version you
+use).</p></li></ul></div><p>
+After a few seconds, there should be a new printer in your
+client's <span class="emphasis"><em>local</em></span> &quot;Printers&quot; folder: On Windows
+XP it will follow a naming convention of <span class="emphasis"><em>PrinterName on
+SambaServer</em></span>. (In my current case it is &quot;infotec_2105 on
+kde-bitshop&quot;). If you want to test it and send your first job from
+an application like Winword, the new printer will appears in a
+<tt class="filename">\\SambaServer\PrinterName</tt> entry in the
+dropdown list of available printers.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+cupsaddsmb will only reliably work with CUPS version 1.1.15 or higher
+and Samba from 2.2.4. If it doesn't work, or if the automatic printer
+driver download to the clients doesn't succeed, you can still manually
+install the CUPS printer PPD on top of the Adobe PostScript driver on
+clients. Then point the client's printer queue to the Samba printer
+share for a UNC type of connection:
+</p></div><pre class="screen">
+
+  net use lpt1: \\sambaserver\printershare /user:ntadmin
+
+</pre><p>
+should you desire to use the CUPS networked PostScript RIP
+functions. (Note that user &quot;ntadmin&quot; needs to be a valid Samba user
+with the required privileges to access the printershare) This would
+set up the printer connection in the traditional
+<span class="emphasis"><em>LanMan</em></span> way (not using MS-RPC).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960474"></a>Avoiding critical PostScript Driver Settings on the
+Client</h3></div></div><div></div></div><p>
+Soooo: printing works, but there are still problems. Most jobs print
+well, some don't print at all. Some jobs have problems with fonts,
+which don't look very good. Some jobs print fast, and some are
+dead-slow. Many of these problems can be greatly reduced or even
+completely eliminated if you follow a few guidelines. Remember, if
+your print device is not PostScript-enabled, you are treating your
+Ghostscript installation on your CUPS host with the output your client
+driver settings produce. Treat it well:
+</p><div class="itemizedlist"><ul type="disc"><li><p>Avoid the <span class="emphasis"><em>PostScript Output Option: Optimize
+for Speed</em></span> setting. Rather use the <span class="emphasis"><em>Optimize for
+Portability</em></span> instead (Adobe PostScript
+driver).</p></li><li><p>Don't use the <span class="emphasis"><em>Page Independence:
+NO</em></span> setting. Instead use <span class="emphasis"><em>Page Independence
+YES</em></span> (CUPS PostScript Driver)</p></li><li><p>Recommended is the <span class="emphasis"><em>True Type Font
+Downloading Option: Native True Type</em></span> over
+<span class="emphasis"><em>Automatic</em></span> and <span class="emphasis"><em>Outline</em></span>; you
+should by all means avoid <span class="emphasis"><em>Bitmap</em></span> (Adobe
+PostScript Driver)</p></li><li><p>Choose <span class="emphasis"><em>True Type Font: Download as Softfont
+into Printer</em></span> over the default <span class="emphasis"><em>Replace by Device
+Font</em></span> (for exotic fonts you may need to change it back to
+get a printout at all) (Adobe)</p></li><li><p>Sometimes you can choose <span class="emphasis"><em>PostScript Language
+Level</em></span>: in case of problems try <span class="emphasis"><em>2</em></span>
+instead of <span class="emphasis"><em>3</em></span> (the latest ESP Ghostscript package
+handles Level 3 PostScript very well) (Adobe).</p></li><li><p>Say <span class="emphasis"><em>Yes</em></span> to <span class="emphasis"><em>PostScript
+Error Handler</em></span> (Adobe)</p></li></ul></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2960608"></a>Installing PostScript Driver Files manually (using
+rpcclient)</h2></div></div><div></div></div><p>
+Of course you can run all the commands which are embedded into the
+cupsaddsmb convenience utility yourself, one by one, and hereby upload
+and prepare the driver files for future client downloads.
+</p><div class="orderedlist"><ol type="1"><li><p>prepare Samba (a CUPS printqueue with the name of the
+printer should be there. We are providing the driver
+now);</p></li><li><p>copy all files to
+<i class="parameter"><tt>[print$]:</tt></i></p></li><li><p>run <b class="command">rpcclient adddriver</b>
+(for each client architecture you want to support):</p></li><li><p>run <b class="command">rpcclient
+setdriver.</b></p></li></ol></div><p>
+We are going to do this now. First, read the man page on &quot;rpcclient&quot;
+to get a first idea. Look at all the printing related
+sub-commands. <b class="command">enumprinters</b>,
+<b class="command">enumdrivers</b>, <b class="command">enumports</b>,
+<b class="command">adddriver</b>, <b class="command">setdriver</b> are amongst
+the most interesting ones. rpcclient implements an important part of
+the MS-RPC protocol. You can use it to query (and command) a Win NT
+(or 2K/XP) PC too. MS-RPC is used by Windows clients, amongst other
+things, to benefit from the &quot;Point'n'Print&quot; features. Samba can now
+mimic this too.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960723"></a>A Check of the rpcclient man Page</h3></div></div><div></div></div><p>
+First let's have a little check of the rpcclient man page. Here are
+two relevant passages:
+</p><p>
+<b class="command">adddriver &lt;arch&gt; &lt;config&gt;</b> Execute an
+AddPrinterDriver() RPC to install the printer driver information on
+the server.  Note that the driver files should already exist in the
+directory returned by <b class="command">getdriverdir</b>.  Possible
+values for <i class="parameter"><tt>arch</tt></i> are the same as those for the
+<b class="command">getdriverdir</b> command.  The
+<i class="parameter"><tt>config</tt></i> parameter is defined as follows:
+</p><pre class="screen">
+Long Printer Name:\
+Driver File Name:\
+Data File Name:\
+Config File Name:\
+Help File Name:\
+Language Monitor Name:\
+Default Data Type:\
+Comma Separated list of Files
+</pre><p>Any empty fields should be enter as the string &quot;NULL&quot;. </p><p>Samba does not need to support the concept of Print Monitors
+since these only apply to local printers whose driver can make use of
+a bi-directional link for communication.  This field should be &quot;NULL&quot;.
+On a remote NT print server, the Print Monitor for a driver must
+already be installed prior to adding the driver or else the RPC will
+fail
+</p><p>
+<b class="command">setdriver &lt;printername&gt; &lt;drivername&gt;</b>
+Execute a <b class="command">SetPrinter()</b> command to update the
+printer driver associated with an installed printer. The printer
+driver must already be correctly installed on the print server.
+</p><p> See also the enumprinters and enumdrivers commands for
+obtaining a list of installed printers and drivers.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960836"></a>Understanding the rpcclient man Page</h3></div></div><div></div></div><p>
+The <span class="emphasis"><em>exact</em></span> format isn't made too clear by the man
+page, since you have to deal with some parameters containing
+spaces. Here is a better description for it. We have line-broken the
+command and indicated the breaks with &quot;\&quot;. Usually you would type the
+command in one line without the linebreaks:
+</p><pre class="screen">
+
+ adddriver &quot;Architecture&quot; \
+           &quot;LongPrinterName:DriverFile:DataFile:ConfigFile:HelpFile:\
+           LanguageMonitorFile:DataType:ListOfFiles,Comma-separated&quot;
+
+</pre><p>
+What the man pages denotes as a simple &lt;config&gt;
+keyword, does in reality consist of 8 colon-separated fields. The
+last field may take multiple (in some, very insane, cases, even
+20 different additional files. This might sound confusing at first.
+Note, that what the man pages names the &quot;LongPrinterName&quot; in
+reality should rather be called the &quot;Driver Name&quot;. You can name it
+anything you want, as long as you use this name later in the
+<span class="emphasis"><em>rpcclient ... setdriver</em></span> command. For
+practical reasons, many name the driver the same as the
+printer.
+</p><p>
+True: it isn't simple at all. I hear you asking:
+<span class="emphasis"><em>How do I know which files are &quot;Driver
+File&quot;, &quot;Data File&quot;, &quot;Config File&quot;, &quot;Help File&quot; and &quot;Language
+Monitor File&quot; in each case?</em></span> -- For an answer you may
+want to have a look at how a Windows NT box with a shared printer
+presents the files to us. Remember, that this whole procedure has
+to be developed by the Samba Team by overhearing the traffic caused
+by Windows computers on the wire. We may as well turn to a Windows
+box now, and access it from a UNIX workstation. We will query it
+with <b class="command">rpcclient</b> to see what it tells us and
+try to understand the man page more clearly which we've read just
+now.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2960925"></a>Producing an Example by querying a Windows Box</h3></div></div><div></div></div><p>
+We could run <b class="command">rpcclient</b> with a
+<b class="command">getdriver</b> or a <b class="command">getprinter</b>
+subcommand (in level 3 verbosity) against it. Just sit down at UNIX or
+Linux workstation with the Samba utilities installed. Then type the
+following command:
+</p><pre class="screen">
+
+ rpcclient -U'USERNAME%PASSWORD' NT-SERVER-NAME -c 'getdriver printername 3'
+
+</pre><p>
+From the result it should become clear which is which. Here is an
+example from my installation:
+</p><pre class="screen">
+
+# rpcclient -U'Danka%xxxx' W2KSERVER -c'getdriver &quot;DANKA InfoStream Virtual Printer&quot; 3'
+ cmd = getdriver &quot;DANKA InfoStream Virtual Printer&quot; 3
+
+ [Windows NT x86]
+ Printer Driver Info 3:
+         Version: [2]
+         Driver Name: [DANKA InfoStream]
+         Architecture: [Windows NT x86]
+         Driver Path: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.DLL]
+         Datafile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\INFOSTRM.PPD]
+         Configfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRPTUI.DLL]
+         Helpfile: [C:\WINNT\System32\spool\DRIVERS\W32X86\2\PSCRIPT.HLP]
+ 
+         Dependentfiles: []
+         Dependentfiles: []
+         Dependentfiles: []
+         Dependentfiles: []
+         Dependentfiles: []
+         Dependentfiles: []
+         Dependentfiles: []
+ 
+         Monitorname: []
+         Defaultdatatype: []
+
+</pre><p>
+Some printer drivers list additional files under the label
+&quot;Dependentfiles&quot;: these would go into the last field
+<span class="emphasis"><em>ListOfFiles,Comma-separated</em></span>. For the CUPS
+PostScript drivers we don't need any (nor would we for the Adobe
+PostScript driver): therefore the field will get a &quot;NULL&quot; entry.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2961015"></a>What is required for adddriver and setdriver to succeed</h3></div></div><div></div></div><p>
+From the manpage (and from the quoted output
+of <span class="emphasis"><em>cupsaddsmb</em></span>, above) it becomes clear that you
+need to have certain conditions in order to make the manual uploading
+and initializing of the driver files succeed. The two rpcclient
+subcommands (<b class="command">adddriver</b> and
+<b class="command">setdriver</b>) need to encounter the following
+pre-conditions to complete successfully:
+</p><div class="itemizedlist"><ul type="disc"><li><p>you are connected as &quot;printer admin&quot;, or root (note,
+that this is <span class="emphasis"><em>not</em></span> the &quot;Printer Operators&quot; group in
+NT, but the <span class="emphasis"><em>printer admin</em></span> group, as defined in
+the <i class="parameter"><tt>[global]</tt></i> section of
+<tt class="filename">smb.conf</tt>);</p></li><li><p>copy all required driver files to
+<tt class="filename">\\sambaserver\print$\w32x86</tt> and
+<tt class="filename">\\sambaserver\print$\win40</tt> as appropriate. They
+will end up in the &quot;0&quot; respective &quot;2&quot; subdirectories later -- for now
+<span class="emphasis"><em>don't</em></span> put them there, they'll be automatically
+used by the <b class="command">adddriver</b> subcommand.! (if you use
+&quot;smbclient&quot; to put the driver files into the share, note that you need
+to escape the &quot;$&quot;: <b class="command">smbclient //sambaserver/print\$ -U
+root</b>);</p></li><li><p>the user you're connecting as must be able to write to
+the <i class="parameter"><tt>[print$]</tt></i> share and create
+subdirectories;</p></li><li><p>the printer you are going to setup for the Windows
+clients, needs to be installed in CUPS already;</p></li><li><p>the CUPS printer must be known to Samba, otherwise the
+<b class="command">setdriver</b> subcommand fails with an
+NT_STATUS_UNSUCCESSFUL error. To check if the printer is known by
+Samba you may use the <b class="command">enumprinters</b> subcommand to
+rpcclient. A long-standing bug prevented a proper update of the
+printer list until every smbd process had received a SIGHUP or was
+restarted. Remember this in case you've created the CUPS printer just
+shortly ago and encounter problems: try restarting
+Samba.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2961177"></a>Manual Commandline Driver Installation in 15 little Steps</h3></div></div><div></div></div><p>
+We are going to install a printer driver now by manually executing all
+required commands. As this may seem a rather complicated process at
+first, we go through the procedure step by step, explaining every
+single action item as it comes up.
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961194"></a>First Step: Install the Printer on CUPS</h4></div></div><div></div></div><pre class="screen">
+
+# lpadmin -p mysmbtstprn -v socket://10.160.51.131:9100 -E -P /home/kurt/canonIR85.ppd
+
+</pre><p>
+This installs printer with the name <span class="emphasis"><em>mysmbtstprn</em></span>
+to the CUPS system. The printer is accessed via a socket
+(a.k.a. JetDirect or Direct TCP/IP) connection. You need to be root
+for this step
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961224"></a>Second Step (optional): Check if the Printer is recognized by
+Samba</h4></div></div><div></div></div><pre class="screen">
+
+ # rpcclient -Uroot%xxxx -c 'enumprinters' localhost | grep -C2 mysmbtstprn
+
+        flags:[0x800000]
+        name:[\\kde-bitshop\mysmbtstprn]
+        description:[\\kde-bitshop\mysmbtstprn,,mysmbtstprn]
+        comment:[mysmbtstprn]
+
+</pre><p>
+This should show the printer in the list. If not, stop and re-start
+the Samba daemon (smbd), or send a HUP signal: <b class="command">kill -HUP
+`pidof smbd`</b>. Check again.  Troubleshoot and repeat until
+success. Note the &quot;empty&quot; field between the two commas in the
+&quot;description&quot; line. Here would the driver name appear if there was one
+already. You need to know root's Samba password (as set by the
+<b class="command">smbpasswd</b> command) for this step and most of the
+following steps. Alternatively you can authenticate as one of the
+users from the &quot;write list&quot; as defined in <tt class="filename">smb.conf</tt> for
+<i class="parameter"><tt>[print$]</tt></i>.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961288"></a>Third Step (optional): Check if Samba knows a Driver for the
+Printer</h4></div></div><div></div></div><pre class="screen">
+
+#  rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost | grep driver
+         drivername:[]
+ 
+#  rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost | grep -C4 driv
+        servername:[\\kde-bitshop]
+        printername:[\\kde-bitshop\mysmbtstprn]
+        sharename:[mysmbtstprn]
+        portname:[Samba Printer Port]
+        drivername:[]
+        comment:[mysmbtstprn]
+        location:[]
+        sepfile:[]
+        printprocessor:[winprint]
+ 
+#  rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost
+ result was WERR_UNKNOWN_PRINTER_DRIVER
+
+</pre><p>
+Neither method of the three commands shown above should show a driver.
+This step was done for the purpose of demonstrating this condition. An
+attempt to connect to the printer at this stage will prompt the
+message along the lines: &quot;The server has not the required printer
+driver installed&quot;.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961326"></a>Fourth Step: Put all required Driver Files into Samba's
+[print$]</h4></div></div><div></div></div><pre class="screen">
+
+#  smbclient //localhost/print\$ -U 'root%xxxx'                        \ 
+                              -c 'cd W32X86;                                             \
+                                  put /etc/cups/ppd/mysmbtstprn.ppd mysmbtstprn.PPD;     \
+                                  put /usr/share/cups/drivers/cupsui.dll cupsui.dll;     \
+                                  put /usr/share/cups/drivers/cupsdrvr.dll cupsdrvr.dll; \
+                                  put /usr/share/cups/drivers/cups.hlp cups.hlp'
+
+</pre><p>
+(Note that this command should be entered in one long single
+line. Line-breaks and the line-end indicating &quot;\&quot; has been inserted
+for readability reasons.) This step is <span class="emphasis"><em>required</em></span>
+for the next one to succeed. It makes the driver files physically
+present in the <i class="parameter"><tt>[print$]</tt></i> share. However, clients
+would still not be able to install them, because Samba does not yet
+treat them as driver files. A client asking for the driver would still
+be presented with a &quot;not installed here&quot; message.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961377"></a>Fifth Step: Verify where the Driver Files are now</h4></div></div><div></div></div><pre class="screen">
+
+#  ls -l /etc/samba/drivers/W32X86/
+ total 669
+ drwxr-sr-x    2 root     ntadmin       532 May 25 23:08 2
+ drwxr-sr-x    2 root     ntadmin       670 May 16 03:15 3
+ -rwxr--r--    1 root     ntadmin     14234 May 25 23:21 cups.hlp
+ -rwxr--r--    1 root     ntadmin    278380 May 25 23:21 cupsdrvr.dll
+ -rwxr--r--    1 root     ntadmin    215848 May 25 23:21 cupsui.dll
+ -rwxr--r--    1 root     ntadmin    169458 May 25 23:21 mysmbtstprn.PPD
+
+</pre><p>
+The driver files now are in the W32X86 architecture &quot;root&quot; of
+<i class="parameter"><tt>[print$]</tt></i>.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961415"></a>Sixth Step: Tell Samba that these are
+<span class="emphasis"><em>Driver</em></span> Files
+(<b class="command">adddriver</b>)</h4></div></div><div></div></div><pre class="screen">
+
+#  rpcclient -Uroot%xxxx -c `adddriver &quot;Windows NT x86&quot; &quot;mydrivername: \
+                                          cupsdrvr.dll:mysmbtstprn.PPD:                  \
+                                          cupsui.dll:cups.hlp:NULL:RAW[<span class="citation">:</span>]NULL&quot;             \
+                                          localhost
+
+ Printer Driver mydrivername successfully installed.
+
+</pre><p>
+Note that your cannot repeat this step if it fails. It could fail even
+as a result of a simple typo. It will most likely have moved a part of
+the driver files into the &quot;2&quot; subdirectory. If this step fails, you
+need to go back to the fourth step and repeat it, before you can try
+this one again. In this step you need to choose a name for your
+driver. It is normally a good idea to use the same name as is used for
+the printername; however, in big installations you may use this driver
+for a number of printers which have obviously different names. So the
+name of the driver is not fixed.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961469"></a>Seventh Step: Verify where the Driver Files are now</h4></div></div><div></div></div><pre class="screen">
+
+#  ls -l /etc/samba/drivers/W32X86/
+ total 1
+ drwxr-sr-x    2 root     ntadmin       532 May 25 23:22 2
+ drwxr-sr-x    2 root     ntadmin       670 May 16 03:15 3
+
+ 
+#  ls -l /etc/samba/drivers/W32X86/2
+ total 5039
+ [....]
+ -rwxr--r--    1 root     ntadmin     14234 May 25 23:21 cups.hlp
+ -rwxr--r--    1 root     ntadmin    278380 May 13 13:53 cupsdrvr.dll
+ -rwxr--r--    1 root     ntadmin    215848 May 13 13:53 cupsui.dll
+ -rwxr--r--    1 root     ntadmin    169458 May 25 23:21 mysmbtstprn.PPD
+
+</pre><p>
+Notice how step 6 did also move the driver files to the appropriate
+subdirectory. Compare with the situation after step 5.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961503"></a>Eighth Step (optional): Verify if Samba now recognizes the
+Driver</h4></div></div><div></div></div><pre class="screen">
+
+#  rpcclient -Uroot%xxxx -c 'enumdrivers 3' localhost | grep -B2 -A5 mydrivername
+
+ Printer Driver Info 3:
+        Version: [2]
+        Driver Name: [mydrivername]
+        Architecture: [Windows NT x86]
+        Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll]
+        Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD]
+        Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll]
+        Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp]
+
+</pre><p>
+Remember, this command greps for the name you did choose for the
+driver in step Six. This command must succeed before you can proceed.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961536"></a>Ninth Step: Tell Samba which Printer should use these Driver
+Files (<b class="command">setdriver</b>)</h4></div></div><div></div></div><pre class="screen">
+
+#  rpcclient -Uroot%xxxx -c 'setdriver mysmbtstprn mydrivername' localhost
+ 
+ Successfully set mysmbtstprn to driver mydrivername
+
+</pre><p>
+Since you can bind any printername (=printqueue) to any driver, this
+is a very convenient way to setup many queues which use the same
+driver. You don't need to repeat all the previous steps for the
+setdriver command to succeed. The only pre-conditions are:
+<b class="command">enumdrivers</b> must find the driver and
+<b class="command">enumprinters</b> must find the printer.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961586"></a>Tenth Step (optional): Verify if Samba has this Association
+recognized</h4></div></div><div></div></div><pre class="screen">
+
+#  rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost | grep driver
+       drivername:[mydrivername]
+ 
+#  rpcclient -Uroot%xxxx -c 'getprinter mysmbtstprn 2' localhost | grep -C4 driv
+       servername:[\\kde-bitshop]
+       printername:[\\kde-bitshop\mysmbtstprn]
+       sharename:[mysmbtstprn]
+       portname:[Done]
+       drivername:[mydrivername]
+       comment:[mysmbtstprn]
+       location:[]
+       sepfile:[]
+       printprocessor:[winprint]
+ 
+#  rpcclient -U root%xxxx -c 'getdriver mysmbtstprn' localhost
+ [Windows NT x86]
+ Printer Driver Info 3:
+       Version: [2]
+       Driver Name: [mydrivername]
+       Architecture: [Windows NT x86]
+       Driver Path: [\\kde-bitshop\print$\W32X86\2\cupsdrvr.dll]
+       Datafile: [\\kde-bitshop\print$\W32X86\2\mysmbtstprn.PPD]
+       Configfile: [\\kde-bitshop\print$\W32X86\2\cupsui.dll]
+       Helpfile: [\\kde-bitshop\print$\W32X86\2\cups.hlp]
+       Monitorname: []
+       Defaultdatatype: [RAW]
+       Monitorname: []
+       Defaultdatatype: [RAW]
+ 
+#  rpcclient -Uroot%xxxx -c 'enumprinters' localhost | grep mysmbtstprn
+       name:[\\kde-bitshop\mysmbtstprn]
+       description:[\\kde-bitshop\mysmbtstprn,mydrivername,mysmbtstprn]
+       comment:[mysmbtstprn]
+
+</pre><p>
+Compare these results with the ones from steps 2 and 3. Note that
+every single of these commands show the driver is installed.  Even
+the <b class="command">enumprinters</b> command now lists the driver
+on the &quot;description&quot; line.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961666"></a>Eleventh Step (optional): Tickle the Driver into a correct
+Device Mode</h4></div></div><div></div></div><p>
+You certainly know how to install the driver on the client.  In case
+you are not particularly familiar with Windows, here is a short
+recipe: browse the Network Neighbourhood, go to the Samba server, look
+for the shares. You should see all shared Samba printers.
+Double-click on the one in question. The driver should get
+installed, and the network connection set up. An alternative way is to
+open the &quot;Printers (and Faxes)&quot; folder, right-click on the printer in
+question and select &quot;Connect&quot; or &quot;Install&quot;. As a result, a new printer
+should have appeared in your client's local &quot;Printers (and Faxes)&quot;
+folder, named something like &quot;printersharename on Sambahostname&quot;.
+</p><p>
+It is important that you execute this step as a Samba printer admin
+(as defined in <tt class="filename">smb.conf</tt>). Here is another method
+to do this on Windows XP. It uses a commandline, which you may type
+into the &quot;DOS box&quot; (type root's smbpassword when prompted):
+</p><pre class="screen">
+
+ C:\&gt; runas /netonly /user:root &quot;rundll32 printui.dll,PrintUIEntry /in /n \\sambacupsserver\mysmbtstprn&quot;
+
+</pre><p>
+Change any printer setting once (like <span class="emphasis"><em>&quot;portrait&quot;
+--&gt; &quot;landscape&quot;</em></span>), click &quot;Apply&quot;; change the setting
+back.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961731"></a>Twelfth Step: Install the Printer on a Client
+(&quot;Point'n'Print&quot;)</h4></div></div><div></div></div><pre class="screen">
+
+ C:\&gt; rundll32 printui.dll,PrintUIEntry /in /n &quot;\\sambacupsserver\mysmbtstprn&quot;
+
+</pre><p>
+If it doesn't work it could be a permission problem with the
+<i class="parameter"><tt>[print$]</tt></i> share.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961764"></a>Thirteenth Step (optional): Print a Test Page</h4></div></div><div></div></div><pre class="screen">
+
+ C:\&gt; rundll32 printui.dll,PrintUIEntry /p /n &quot;\\sambacupsserver\mysmbtstprn&quot;
+
+</pre><p>
+Then hit [TAB] 5 times, [ENTER] twice, [TAB] once and [ENTER] again
+and march to the printer.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961790"></a>Fourteenth Step (recommended): Study the Test Page</h4></div></div><div></div></div><p>
+Hmmm.... just kidding! By now you know everything about printer
+installations and you don't need to read a word. Just put it in a
+frame and bolt it to the wall with the heading &quot;MY FIRST
+RPCCLIENT-INSTALLED PRINTER&quot; - why not just throw it away!
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2961808"></a>Fifteenth Step (obligatory): Enjoy. Jump. Celebrate your
+Success</h4></div></div><div></div></div><pre class="screen">
+
+# echo &quot;Cheeeeerioooooo! Success...&quot; &gt;&gt; /var/log/samba/log.smbd     
+
+</pre></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2961830"></a>Troubleshooting revisited</h3></div></div><div></div></div><p>
+The setdriver command will fail, if in Samba's mind the queue is not
+already there. You had promising messages about the:
+</p><pre class="screen">
+
+ Printer Driver ABC successfully installed.
+
+</pre><p>
+after the &quot;adddriver&quot; parts of the procedure?  But you are also seeing
+a disappointing message like this one beneath?
+</p><pre class="screen">
+
+ result was NT_STATUS_UNSUCCESSFUL
+
+</pre><p>
+It is not good enough that <span class="emphasis"><em>you</em></span>
+can see the queue <span class="emphasis"><em>in CUPS</em></span>, using
+the <b class="command">lpstat -p ir85wm</b> command. A
+bug in most recent versions of Samba prevents the proper update of
+the queuelist. The recognition of newly installed CUPS printers
+fails unless you re-start Samba or send a HUP to all smbd
+processes. To verify if this is the reason why Samba doesn't
+execute the setdriver command successfully, check if Samba &quot;sees&quot;
+the printer: 
+</p><pre class="screen">
+
+# rpcclient transmeta -N -U'root%secret' -c 'enumprinters 0'| grep  ir85wm
+        printername:[ir85wm]
+
+</pre><p>
+An alternative command could be this: 
+</p><pre class="screen">
+
+# rpcclient transmeta -N -U'root%secret' -c 'getprinter ir85wm' 
+        cmd = getprinter ir85wm
+        flags:[0x800000]
+        name:[\\transmeta\ir85wm]
+        description:[\\transmeta\ir85wm,ir85wm,DPD]
+        comment:[CUPS PostScript-Treiber for WinNT/2K/XP]
+
+</pre><p>
+BTW, you can use these commands, plus a few more, of course,
+to install drivers on remote Windows NT print servers too!
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2961930"></a>The printing <tt class="filename">*.tdb</tt> Files</h2></div></div><div></div></div><p>
+Some mystery is associated with the series of files with a
+tdb-suffix appearing in every Samba installation. They are
+<tt class="filename">connections.tdb</tt>,
+<tt class="filename">printing.tdb</tt>,
+<tt class="filename">share_info.tdb</tt> ,
+<tt class="filename">ntdrivers.tdb</tt>,
+<tt class="filename">unexpected.tdb</tt>,
+<tt class="filename">brlock.tdb</tt> ,
+<tt class="filename">locking.tdb</tt>,
+<tt class="filename">ntforms.tdb</tt>,
+<tt class="filename">messages.tdb</tt> ,
+<tt class="filename">ntprinters.tdb</tt>,
+<tt class="filename">sessionid.tdb</tt> and
+<tt class="filename">secrets.tdb</tt>. What is their purpose?
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2962033"></a>Trivial DataBase Files</h3></div></div><div></div></div><p>
+A Windows NT (Print) Server keeps track of all information needed to serve
+its duty toward its clients by storing entries in the Windows
+&quot;Registry&quot;. Client queries are answered by reading from the registry,
+Administrator or user configuration settings are saved by writing into
+the Registry. Samba and Unix obviously don't have such a kind of
+Registry. Samba instead keeps track of all client related information in a
+series of <tt class="filename">*.tdb</tt> files. (TDB = Trivial Data
+Base). These are often located in <tt class="filename">/var/lib/samba/</tt>
+or <tt class="filename">/var/lock/samba/</tt> . The printing related files
+are <tt class="filename">ntprinters.tdb</tt>,
+<tt class="filename">printing.tdb</tt>,<tt class="filename">ntforms.tdb</tt> and
+<tt class="filename">ntdrivers.tdb</tt>.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2962103"></a>Binary Format</h3></div></div><div></div></div><p>
+<tt class="filename">*.tdb</tt> files are not human readable. They are
+written in a binary format. &quot;Why not ASCII?&quot;, you may ask. &quot;After all,
+ASCII configuration files are a good and proofed tradition on UNIX.&quot;
+-- The reason for this design decision by the Samba Team is mainly
+performance. Samba needs to be fast; it runs a separate
+<b class="command">smbd</b> process for each client connection, in some
+environments many thousand of them. Some of these smbds might need to
+write-access the same <tt class="filename">*.tdb</tt> file <span class="emphasis"><em>at the
+same time</em></span>. The file format of Samba's
+<tt class="filename">*.tdb</tt> files allows for this provision. Many smbd
+processes may write to the same <tt class="filename">*.tdb</tt> file at the
+same time. This wouldn't be possible with pure ASCII files.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2962165"></a>Losing <tt class="filename">*.tdb</tt> Files</h3></div></div><div></div></div><p>
+It is very important that all <tt class="filename">*.tdb</tt> files remain
+consistent over all write and read accesses. However, it may happen
+that these files <span class="emphasis"><em>do</em></span> get corrupted. (A
+<b class="command">kill -9 `pidof smbd`</b> while a write access is in
+progress could do the damage as well as a power interruption,
+etc.). In cases of trouble, a deletion of the old printing-related
+<tt class="filename">*.tdb</tt> files may be the only option. You need to
+re-create all print related setup after that.  Or you have made a
+backup of the <tt class="filename">*.tdb</tt> files in time.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2962224"></a>Using <span class="emphasis"><em>tdbbackup</em></span></h3></div></div><div></div></div><p>
+Samba ships with a little utility which helps the root user of your
+system to back up your <tt class="filename">*.tdb</tt> files. If you run it
+with no argument, it prints a little usage message:
+</p><pre class="screen">
+
+# tdbbackup
+ Usage: tdbbackup [options] &lt;fname...&gt;
+ 
+ Version:3.0a
+   -h            this help message
+   -s suffix     set the backup suffix
+   -v            verify mode (restore if corrupt)
+
+</pre><p>
+Here is how I backed up my printing.tdb file:
+</p><pre class="screen">
+
+# ls 
+ .           browse.dat       locking.tdb     ntdrivers.tdb   printing.tdb    share_info.tdb
+ ..          connections.tdb  messages.tdb    ntforms.tdb     printing.tdbkp  unexpected.tdb
+ brlock.tdb  gmon.out         namelist.debug  ntprinters.tdb  sessionid.tdb
+ 
+ kde-bitshop:/var/lock/samba # tdbbackup -s .bak printing.tdb
+ printing.tdb : 135 records
+ 
+ kde-bitshop:/var/lock/samba # ls -l printing.tdb*
+ -rw-------    1 root     root        40960 May  2 03:44 printing.tdb
+ -rw-------    1 root     root        40960 May  2 03:44 printing.tdb.bak
+
+</pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2962290"></a>CUPS Print Drivers from Linuxprinting.org</h2></div></div><div></div></div><p>
+CUPS ships with good support for HP LaserJet type printers.  You can
+install the generic driver as follows:
+</p><pre class="screen">
+
+lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -m laserjet.ppd
+
+</pre><p>
+The <i class="parameter"><tt>-m</tt></i> switch will retrieve the
+<tt class="filename">laserjet.ppd</tt> from the standard repository for
+not-yet-installed-PPDs, which CUPS typically stores in
+<tt class="filename">/usr/share/cups/model</tt>. Alternatively, you may use
+<i class="parameter"><tt>-P /path/to/your.ppd</tt></i>.
+</p><p>
+The generic laserjet.ppd however does not support every special option
+for every LaserJet-compatible model. It constitutes a sort of &quot;least
+denominator&quot; of all the models. If for some reason it is ruled out to
+you to pay for the commercially available ESP Print Pro drivers, your
+first move should be to consult the database on <a href="http://www.linuxprinting.org/printer_list.cgi" target="_top">http://www.linuxprinting.org/printer_list.cgi</a>.
+Linuxprinting.org has excellent recommendations about which driver is
+best used for each printer. Its database is kept current by the
+tireless work of Till Kamppeter from MandrakeSoft, who is also the
+principal author of the foomatic-rip utility.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+The former &quot;cupsomatic&quot; concept is now be replaced by the new, much
+more powerful &quot;foomatic-rip&quot;. foomatic-rip is the successor of
+cupsomatic. cupsomatic is no longer maintained. Here is the new URL
+to the Foomatic-3.0 database:<a href="http://www.linuxprinting.org/driver_list.cgi" target="_top">http://www.linuxprinting.org/driver_list.cgi</a>.
+If you upgrade to foomatic-rip, don't forget to also upgrade to the
+new-style PPDs for your foomatic-driven printers. foomatic-rip will
+not work with PPDs generated for the old cupsomatic. The new-style
+PPDs are 100% compliant to the Adobe PPD specification. They are
+intended to be used by Samba and the cupsaddsmb utility also, to
+provide the driver files for the Windows clients also!
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2962398"></a>foomatic-rip and Foomatic explained</h3></div></div><div></div></div><p>
+Nowadays most Linux distros rely on the utilities of Linuxprinting.org
+to create their printing related software (which, BTW, works on all
+UNIXes and on Mac OS X or Darwin too). It is not known as well as it
+should be, that it also has a very end-user friendly interface which
+allows for an easy update of drivers and PPDs, for all supported
+models, all spoolers, all operating systems and all package formats
+(because there is none). Its history goes back a few years.
+</p><p>
+Recently Foomatic has achieved the astonishing milestone of <a href="http://www.linuxprinting.org/printer_list.cgi?make=Anyone" target="_top">1000
+listed</a> printer models. Linuxprinting.org keeps all the
+important facts about printer drivers, supported models and which
+options are available for the various driver/printer combinations in
+its <a href="http://www.linuxprinting.org/foomatic.html" target="_top">Foomatic</a>
+database. Currently there are <a href="http://www.linuxprinting.org/driver_list.cgi" target="_top">245 drivers</a>
+in the database: many drivers support various models, and many models
+may be driven by different drivers; it's your choice!
+</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962453"></a>690 &quot;perfect&quot; Printers</h4></div></div><div></div></div><p>
+At present there are 690 devices dubbed as working &quot;perfectly&quot;, 181
+&quot;mostly&quot;, 96 &quot;partially&quot; and 46 are &quot;Paperweights&quot;. Keeping in mind
+that most of these are non-PostScript models (PostScript printers are
+automatically supported supported by CUPS to perfection, by using
+their own manufacturer-provided Windows-PPD...), and that a
+multifunctional device never qualifies as working &quot;perfectly&quot; if it
+doesn't also scan and copy and fax under GNU/Linux: then this is a
+truly astonishing achievement. Three years ago the number was not
+more than 500, and Linux or UNIX &quot;printing&quot; at the time wasn't
+anywhere near the quality it is today!
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962477"></a>How the &quot;Printing HOWTO&quot; started it all</h4></div></div><div></div></div><p>
+A few years ago <a href="http://www2.picante.com:81/~gtaylor/" target="_top">Grant Taylor</a>
+started it all. The roots of today's Linuxprinting.org are in the
+first <a href="http://www.linuxprinting.org/foomatic2.9/howto/" target="_top">Linux Printing
+HOWTO</a> which he authored. As a side-project to this document,
+which served many Linux users and admins to guide their first steps in
+this complicated and delicate setup (to a scientist, printing is
+&quot;applying a structured deposition of distinct patterns of ink or toner
+particles on paper substrates&quot; <span class="emphasis"><em>;-)</em></span>, he started to
+build in a little Postgres database with information about the
+hardware and driver zoo that made up Linux printing of the time. This
+database became the core component of today's Foomatic collection of
+tools and data. In the meantime it has moved to an XML representation
+of the data.
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962522"></a>Foomatic's strange Name</h4></div></div><div></div></div><p>
+&quot;Why the funny name?&quot;, you ask. When it really took off, around spring
+2000, CUPS was far less popular than today, and most systems used LPD,
+LPRng or even PDQ to print. CUPS shipped with a few generic &quot;drivers&quot;
+(good for a few hundred different printer models). These didn't
+support many device-specific options. CUPS also shipped with its own
+built-in rasterization filter (&quot;pstoraster&quot;, derived from
+Ghostscript). On the other hand, CUPS provided brilliant support for
+<span class="emphasis"><em>controlling</em></span> all printer options through
+standardized and well-defined &quot;PPD files&quot; (PostScript Printers
+Description files). Plus, CUPS was designed to be easily extensible.
+</p><p>
+Grant already had in his database a respectable compilation
+of facts about a many more printers, and the Ghostscript &quot;drivers&quot;
+they run with. His idea, to generate PPDs from the database info
+and use them to make standard Ghostscript filters work within CUPS,
+proved to work very well. It also &quot;killed several birds with one
+stone&quot;:
+</p><div class="itemizedlist"><ul type="disc"><li><p>It made all current and future Ghostscript filter
+developments available for CUPS;</p></li><li><p>It made available a lot of additional printer models
+to CUPS users (because often the &quot;traditional&quot; Ghostscript way of
+printing was the only one available);</p></li><li><p>It gave all the advanced CUPS options (web interface,
+GUI driver configurations) to users wanting (or needing) to use
+Ghostscript filters.</p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962589"></a>cupsomatic, pdqomatic, lpdomatic, directomatic</h4></div></div><div></div></div><p>
+CUPS worked through a quickly-hacked up filter script named <a href="http://www.linuxprinting.org/download.cgi?filename=cupsomatic&amp;show=0" target="_top">cupsomatic</a>.
+cupsomatic ran the printfile through Ghostscript, constructing
+automatically the rather complicated command line needed. It just
+required to be copied into the CUPS system to make it work. To
+&quot;configure&quot; the way cupsomatic controls the Ghostscript rendering
+process, it needs a CUPS-PPD. This PPD is generated directly from the
+contents of the database. For CUPS and the respective printer/filter
+combo another Perl script named &quot;CUPS-O-Matic&quot; did the PPD
+generation. After that was working, Grant implemented within a few
+days a similar thing for two other spoolers. Names chosen for the
+config-generator scripts were <a href="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&amp;show=0" target="_top">PDQ-O-Matic</a>
+(for PDQ) and <a href="http://www.linuxprinting.org/download.cgi?filename=lpdomatic&amp;show=0" target="_top">LPD-O-Matic</a>
+(for - you guessed it - LPD); the configuration here didn't use PPDs
+but other spooler-specific files.
+</p><p>
+From late summer of that year, <a href="http://www.linuxprinting.org/till/" target="_top">Till Kamppeter</a>
+started to put work into the database. Till had been newly employed by
+<a href="http://www.mandrakesoft.com/" target="_top">MandrakeSoft</a> to
+convert their printing system over to CUPS, after they had seen his
+<a href="http://www.fltk.org/" target="_top">FLTK</a>-based <a href="http://cups.sourceforge.net/xpp/" target="_top">XPP</a> (a GUI frontend to
+the CUPS lp-command). He added a huge amount of new information and new
+printers. He also developed the support for other spoolers, like
+<a href="http://ppr.sourceforge.net/" target="_top">PPR</a> (via ppromatic),
+<a href="http://sourceforge.net/projects/lpr/" target="_top">GNUlpr</a> and
+<a href="http://www.lprng.org/" target="_top">LPRng</a> (both via an extended
+lpdomatic) and &quot;spoolerless&quot; printing (<a href="http://www.linuxprinting.org/download.cgi?filename=directomatic&amp;show=0" target="_top">directomatic</a>)....
+</p><p>
+So, to answer your question: &quot;Foomatic&quot; is the general name for all
+the overlapping code and data behind the &quot;*omatic&quot; scripts.... --
+Foomatic up to versions 2.0.x required (ugly) Perl data structures
+attached the Linuxprinting.org PPDs for CUPS. It had a different
+&quot;*omatic&quot; script for every spooler, as well as different printer
+configuration files..
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962725"></a>7.13.1.5.The <span class="emphasis"><em>Grand Unification</em></span>
+achieved...</h4></div></div><div></div></div><p>
+This all has changed in Foomatic versions 2.9 (Beta) and released as
+&quot;stable&quot; 3.0. This has now achieved the convergence of all *omatic
+scripts: it is called the <a href="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&amp;show=0" target="_top">foomatic-rip</a>.
+This single script is the unification of the previously different
+spooler-specific *omatic scripts. foomatic-rip is used by all the
+different spoolers alike. Because foomatic-rip can read PPDs (both the
+original PostScript printer PPDs and the Linuxprinting.org-generated
+ones), all of a sudden all supported spoolers can have the power of
+PPDs at their disposal; users only need to plug &quot;foomatic-rip&quot; into
+their system.... For users there is improved media type and source
+support; paper sizes and trays are easier to configure.
+</p><p>
+Also, the New Generation of Linuxprinting.org PPDs doesn't contain
+Perl data structures any more. If you are a distro maintainer and have
+used the previous version of Foomatic, you may want to give the new
+one a spin: but don't forget to generate a new-version set of PPDs,
+via the new <a href="http://www.linuxprinting.org/download/foomatic/foomatic-db-engine-3.0.0beta1.tar.gz" target="_top">foomatic-db-engine</a>!
+Individual users just need to generate a single new PPD specific to
+their model by <a href="http://www.linuxprinting.org/kpfeifle/LinuxKongress2002/Tutorial/II.Foomatic-User/II.tutorial-handout-foomatic-user.html" target="_top">following
+the steps</a> outlined in the Foomatic tutorial or further
+below. This new development is truly amazing.
+</p><p>
+foomatic-rip is a very clever wrapper around the need to run
+Ghostscript with a different syntax, different options, different
+device selections and/or different filters for each different printer
+or different spooler. At the same time it can read the PPD associated
+with a print queue and modify the print job according to the user
+selections. Together with this comes the 100% compliance of the new
+Foomatic PPDs with the Adobe spec. Some really innovative features of
+the Foomatic concept will surprise users: it will support custom paper
+sizes for many printers; and it will support printing on media drawn
+from different paper trays within the same job (in both cases: even
+where there is no support for this from Windows-based vendor printer
+drivers).
+</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962810"></a>Driver Development outside</h4></div></div><div></div></div><p>
+Most driver development itself does not happen within
+Linuxprinting.org. Drivers are written by independent maintainers.
+Linuxprinting.org just pools all the information, and stores it in its
+database. In addition, it also provides the Foomatic glue to integrate
+the many drivers into any modern (or legacy) printing system known to
+the world.
+</p><p>
+Speaking of the different driver development groups: most of
+the work is currently done in three projects. These are:
+</p><div class="itemizedlist"><ul type="disc"><li><p><a href="http://www-124.ibm.com/developerworks/oss/linux/projects/omni/" target="_top">Omni</a>
+-- a Free Software project by IBM which tries to convert their printer
+driver knowledge from good-ol' OS/2 times into a modern, modular,
+universal driver architecture for Linux/Unix (still Beta).  This
+currently supports 437 models.</p></li><li><p><a href="http://hpinkjet.sf.net/" target="_top">HPIJS</a> --
+a Free Software project by HP to provide the support for their own
+range of models (very mature, printing in most cases is perfect and
+provides true photo quality). This currently supports 369
+models.</p></li><li><p><a href="http://gimp-print.sf.net/" target="_top">Gimp-Print</a> -- a Free software
+effort, started by Michael Sweet (also lead developer for CUPS), now
+directed by Robert Krawitz, which has achieved an amazing level of
+photo print quality (many Epson users swear that its quality is
+better than the vendor drivers provided by Epson for the Microsoft
+platforms). This currently supports 522 models.</p></li></ul></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962892"></a>Forums, Downloads, Tutorials, Howtos -- also for Mac OS X and
+commercial Unix</h4></div></div><div></div></div><p>
+Linuxprinting.org today is the one-stop &quot;shop&quot; to download printer
+drivers. Look for printer information and <a href="http://www.linuxprinting.org//kpfeifle/LinuxKongress2002/Tutorial/" target="_top">tutorials</a>
+or solve printing problems in its popular <a href="http://www.linuxprinting.org/newsportal/" target="_top">forums</a>.  But
+it's not just for GNU/Linux: users and admins of <a href="http://www.linuxprinting.org/macosx/" target="_top">commercial UNIX
+systems</a> are also going there, and the relatively new <a href="http://www.linuxprinting.org/newsportal/thread.php3?name=linuxprinting.macosx.general" target="_top">Mac
+OS X forum</a> has turned out to be one of the most frequented
+fora after only a few weeks.
+</p><p>
+Linuxprinting.org and the Foomatic driver wrappers around Ghostscript
+are now a standard toolchain for printing on all the important
+distros. Most of them also have CUPS underneath. While in recent years
+most printer data had been added by Till (who works at Mandrake), many
+additional contributions came from engineers with SuSE, RedHat,
+Connectiva, Debian and others. Vendor-neutrality is an important goal
+of the Foomatic project.
+</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+Till Kamppeter from MandrakeSoft is doing an excellent job in his
+spare time to maintain Linuxprinting.org and Foomatic. So if you use
+it often, please send him a note showing your appreciation.
+</p></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2962963"></a>Foomatic Database generated PPDs</h4></div></div><div></div></div><p>
+The Foomatic database is an amazing piece of ingenuity in itself. Not
+only does it keep the printer and driver information, but it is
+organized in a way that it can generate &quot;PPD&quot; files &quot;on the fly&quot; from
+its internal XML-based datasets. While these PPDs are modelled to the
+Adobe specification of &quot;PostScript Printer Descriptions&quot; (PPDs), the
+Linuxprinting.org/Foomatic-PPDs don't normally drive PostScript
+printers: they are used to describe all the bells and whistles you
+could ring or blow on an Epson Stylus inkjet, or a HP Photosmart or
+what-have-you. The main &quot;trick&quot; is one little additional line, not
+envisaged by the PPD specification, starting with the &quot;*cupsFilter&quot;
+keyword: it tells the CUPS daemon how to proceed with the PostScript
+print file (old-style Foomatic-PPDs named the
+<span class="emphasis"><em>cupsomatic</em></span> filter script, while the new-style
+PPDs now call <span class="emphasis"><em>foomatic-rip</em></span>). This filter
+script calls Ghostscript on the host system (the recommended variant
+is ESP Ghostscript) to do the rendering work. foomatic-rip knows which
+filter or internal device setting it should ask from Ghostscript to
+convert the PostScript printjob into a raster format ready for the
+target device. This usage of PPDs to describe the options of non-PS
+printers was the invention of the CUPS developers. The rest is easy:
+GUI tools (like KDE's marvellous <a href="http://printing.kde.org/overview/kprinter.phtml" target="_top">&quot;kprinter&quot;</a>,
+or the GNOME <a href="http://gtklp.sourceforge.net/" target="_top">&quot;gtklp&quot;</a>, &quot;xpp&quot; and the CUPS
+web interface) read the PPD too and use this information to present
+the available settings to the user as an intuitive menu selection.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963027"></a>foomatic-rip and Foomatic-PPD Download and Installation</h3></div></div><div></div></div><p>
+Here are the steps to install a foomatic-rip driven &quot;LaserJet 4 Plus&quot;
+compatible printer in CUPS (note that recent distributions of SuSE,
+UnitedLinux and Mandrake may ship with a complete package of
+Foomatic-PPDs plus the foomatic-rip utility.  going directly to
+Linuxprinting.org ensures you to get the latest driver/PPD files):
+</p><div class="itemizedlist"><ul type="disc"><li><p>Surf to <a href="http://www.linuxprinting.org/printer_list.cgi" target="_top">http://www.linuxprinting.org/printer_list.cgi</a>
+</p></li><li><p>Check the complete list of printers in the database:
+<a href="http://www.linuxprinting.org/printer_list.cgi?make=Anyone" target="_top">http://www.linuxprinting.org/printer_list.cgi?make=Anyone</a>
+</p></li><li><p>There select your model and click on the
+link.</p></li><li><p>You'll arrive at a page listing all drivers working
+with this model (for all printers, there will always be
+<span class="emphasis"><em>one</em></span> recommended driver. Try this one
+first).</p></li><li><p>In our case (&quot;HP LaserJet 4 Plus&quot;), we'll arrive here:
+<a href="http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_4_Plus" target="_top">http://www.linuxprinting.org/show_printer.cgi?recnum=HP-LaserJet_4_Plus</a>
+</p></li><li><p>The recommended driver is &quot;ljet4&quot;.</p></li><li><p>There are several links provided here. You should
+visit them all, if you are not familiar with the Linuxprinting.org
+database.</p></li><li><p>There is a link to the database page for the &quot;ljet4&quot;:
+<a href="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4" target="_top">http://www.linuxprinting.org/show_driver.cgi?driver=ljet4</a>
+On the driver's page, you'll find important and detailed information
+about how to use that driver within the various available
+spoolers.</p></li><li><p>Another link may lead you to the homepage of the
+driver author or the driver.</p></li><li><p>Important links are the ones which provide hints with
+setup instructions for CUPS (<a href="http://www.linuxprinting.org/cups-doc.html" target="_top">http://www.linuxprinting.org/cups-doc.html</a>),
+PDQ (<a href="http://www.linuxprinting.org/pdq-doc.html" target="_top">http://www.linuxprinting.org/pdq-doc.html</a>),
+LPD, LPRng and GNUlpr (<a href="http://www.linuxprinting.org/lpd-doc.html" target="_top">http://www.linuxprinting.org/lpd-doc.html</a>)
+as well as PPR (<a href="http://www.linuxprinting.org/ppr-doc.html" target="_top">http://www.linuxprinting.org/ppr-doc.html)</a>
+or &quot;spooler-less&quot; printing (<a href="http://www.linuxprinting.org/direct-doc.html" target="_top">http://www.linuxprinting.org/direct-doc.html</a>
+).</p></li><li><p>You can view the PPD in your browser through this
+link: <a href="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&amp;printer=HP-LaserJet_4_Plus&amp;show=1" target="_top">http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&amp;printer=HP-LaserJet_4_Plus&amp;show=1</a>
+</p></li><li><p>You can also (most importantly)
+generate and download the PPD: <a href="http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&amp;printer=HP-LaserJet_4_Plus&amp;show=0" target="_top">http://www.linuxprinting.org/ppd-o-matic.cgi?driver=ljet4&amp;printer=HP-LaserJet_4_Plus&amp;show=0</a>
+</p></li><li><p>The PPD contains all the information needed to use our
+model and the driver; this is, once installed, working transparently
+for the user. Later 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.</p></li><li><p>Should you have ended up on the driver's page (<a href="http://www.linuxprinting.org/show_driver.cgi?driver=ljet4" target="_top">http://www.linuxprinting.org/show_driver.cgi?driver=ljet4</a>),
+you can choose to use the &quot;PPD-O-Matic&quot; online PPD generator
+program.</p></li><li><p>Select the exact model and check either &quot;download&quot; or
+&quot;display PPD file&quot; and click on &quot;Generate PPD file&quot;.</p></li><li><p>If you save the PPD file from the browser view, please
+don't use &quot;cut'n'past&quot; (since it could possibly damage line endings
+and tabs, which makes the PPD likely to fail its duty), but use &quot;Save
+as...&quot; in your browser's menu. (Best is to use the &quot;download&quot; option
+from the web page directly).</p></li><li><p>Another very interesting part on each driver page is
+the <span class="emphasis"><em>Show execution details</em></span> button. If you
+select your printer model and click that button, you will get
+displayed a complete Ghostscript command line, enumerating all options
+available for that driver/printermodel combo. This is a great way to
+&quot;Learn Ghostscript By Doing&quot;. It is also an excellent &quot;cheat sheet&quot;
+for all experienced users who need to re-construct a good command line
+for that damn printing script, but can't remember the exact
+syntax. ;-)</p></li><li><p>Some time during your visit to Linuxprinting.org, save
+the PPD to a suitable place on your harddisk, say
+<tt class="filename">/path/to/my-printer.ppd</tt> (if you prefer to install
+your printers with the help of the CUPS web interface, save the PPD to
+the <tt class="filename">/usr/share/cups/model/</tt> path and re-start
+cupsd).</p></li><li><p>Then install the printer with a suitable commandline,
+e.g.: 
+</p><pre class="screen">
+
+lpadmin -p laserjet4plus -v parallel:/dev/lp0 -E -P path/to/my-printer.ppd
+
+</pre></li><li><p>Note again this: for all the new-style &quot;Foomatic-PPDs&quot;
+from Linuxprinting.org, you also need a special &quot;CUPS filter&quot; named
+&quot;foomatic-rip&quot;.Get the latest version of &quot;foomatic-rip&quot; from: <a href="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&amp;show=0" target="_top">http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&amp;show=0</a>
+</p></li><li><p>The foomatic-rip Perlscript itself also makes some
+interesting reading (<a href="http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&amp;show=1" target="_top">http://www.linuxprinting.org/foomatic2.9/download.cgi?filename=foomatic-rip&amp;show=1</a>),
+because it is very well documented by Till's inline comments (even
+non-Perl hackers will learn quite a bit about printing by reading
+it... ;-)</p></li><li><p>Save foomatic-rip either directly in
+<tt class="filename">/usr/lib/cups/filter/foomatic-rip</tt> or somewhere in
+your $PATH (and don't forget to make it world-executable). Again,
+don't save by &quot;copy'n'paste&quot; but use the appropriate link, or the
+&quot;Save as...&quot;  menu item in your browser.</p></li><li><p>If you save foomatic-rip in your $PATH, create a symlink:
+<b class="command">cd /usr/lib/cups/filter/ ; ln -s `which
+foomatic-rip`</b>. For CUPS to discover this new
+available filter at startup, you need to re-start
+cupsd.</p></li></ul></div><p>
+Once you print to a printqueue set up with the Foomatic-PPD, CUPS will
+insert the appropriate commands and comments into the resulting
+PostScript jobfile. foomatic-rip is able to read and act upon
+these. foomatic-rip uses some specially encoded Foomatic comments,
+embedded in the jobfile. These in turn are used to construct
+(transparently for you, the user) the complicated ghostscript command
+line telling for the printer driver how exactly the resulting raster
+data should look like and which printer commands to embed into the
+data stream.
+</p><p>
+You need:
+</p><div class="itemizedlist"><ul type="disc"><li><p>A &quot;foomatic+something&quot; PPD -- but it this not enough
+to print with CUPS (it is only <span class="emphasis"><em>one</em></span> important
+component)</p></li><li><p>The &quot;foomatic-rip&quot; filter script (Perl) in
+/usr/lib/cups/filters/</p></li><li><p>Perl to make foomatic-rip run</p></li><li><p>Ghostscript (because it is doing the main work,
+controlled by the PPD/foomatic-rip combo) to produce the raster data
+fit for your printermodel's consumption</p></li><li><p>Ghostscript <span class="emphasis"><em>must</em></span> (depending on
+the driver/model) contain support for a certain &quot;device&quot;, representing
+the selected &quot;driver&quot; for your model (as shown by &quot;gs
+-h&quot;)</p></li><li><p>foomatic-rip needs a new version of PPDs (PPD versions
+produced for cupsomatic don't work with
+foomatic-rip).</p></li></ul></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2963488"></a>Page Accounting with CUPS</h2></div></div><div></div></div><p>
+Often there are questions regarding &quot;print quotas&quot; wherein Samba users
+(that is, Windows clients) should not be able to print beyond a
+certain amount of pages or data volume per day, week or month. This
+feature is dependent on the real print subsystem you're using.
+Samba's part is always to receive the job files from the clients
+(filtered <span class="emphasis"><em>or</em></span> unfiltered) and hand it over to this
+printing subsystem.
+</p><p>
+Of course one could &quot;hack&quot; things with one's own scripts. But then
+there is CUPS. CUPS supports &quot;quotas&quot; which can be based on sizes of
+jobs or on the number of pages or both, and are spanning any time
+period you want.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963519"></a>Setting up Quotas</h3></div></div><div></div></div><p>
+This is an example command how root would set a print quota in CUPS,
+assuming an existing printer named &quot;quotaprinter&quot;:
+</p><pre class="screen">
+
+  lpadmin -p quotaprinter -o job-quota-period=604800 -o job-k-limit=1024 -o job-page-limit=100
+
+</pre><p>
+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).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963551"></a>Correct and incorrect Accounting</h3></div></div><div></div></div><p>
+For CUPS to count correctly, the printfile needs to pass the CUPS
+&quot;pstops&quot; filter, otherwise it uses a &quot;dummy&quot; count of &quot;1&quot;.  Some
+printfiles don't pass it (eg: image files) but then those are mostly 1
+page jobs anyway. This also means that proprietary drivers for the
+target printer running on the client computers and CUPS/Samba, which
+then spool these files as &quot;raw&quot; (i.e. leaving them untouched, not
+filtering them), will be counted as &quot;1-pagers&quot; too!
+</p><p>
+You need to send PostScript from the clients (i.e. run a PostScript
+driver there) to have 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 about 1,000 different printer models,
+see <a href="http://www.linuxprinting.org/printer_list.cgi" target="_top">http://www.linuxprinting.org/printer_list.cgi</a>).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963592"></a>Adobe and CUPS PostScript Drivers for Windows Clients</h3></div></div><div></div></div><p>
+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 through the &quot;pstops&quot; filter on the CUPS/Samba side, and
+therefore was not counted correctly (the reason is that it often,
+depending on the &quot;PPD&quot; being used, wrote a &quot;PJL&quot;-header in front of
+the real PostScript which caused CUPS to skip pstops and go directly
+to the &quot;pstoraster&quot; stage).
+</p><p>
+From CUPS-1.1.16 onward you can use the &quot;CUPS PostScript Driver for
+Windows NT/2K/XP clients&quot; (which is tagged in the download area of
+http://www.cups.org/ as the &quot;cups-samba-1.1.16.tar.gz&quot; package). It does
+<span class="emphasis"><em>not</em></span> work for Win9x/ME clients. But it guarantees:
+</p><div class="itemizedlist"><ul type="disc"><li><p>to not write an PJL-header</p></li><li><p>to still read and support all PJL-options named in the
+driver PPD with its own means</p></li><li><p> that the file will pass through the &quot;pstops&quot; filter
+on the CUPS/Samba server</p></li><li><p>to page-count correctly the
+printfile</p></li></ul></div><p>
+You can read more about the setup of this combination in the manpage
+for &quot;cupsaddsmb&quot; (which is only present with CUPS installed, and only
+current from CUPS 1.1.16).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963663"></a>The page_log File Syntax</h3></div></div><div></div></div><p>
+These are the items CUPS logs in the &quot;page_log&quot; for every
+single <span class="emphasis"><em>page</em></span> of a job:
+</p><div class="itemizedlist"><ul type="disc"><li><p>Printer name</p></li><li><p>User name</p></li><li><p>Job ID</p></li><li><p>Time of printing</p></li><li><p>the page number</p></li><li><p>the number of copies</p></li><li><p>a billing information string
+(optional)</p></li><li><p>the host which sent the job (included since version
+1.1.19)</p></li></ul></div><p>
+Here is an extract of my CUPS server's page_log file to illustrate the
+format and included items:
+</p><pre class="screen">
+
+        infotec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 1 3 #marketing 10.160.50.13
+        infotec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 2 3 #marketing 10.160.50.13
+        infotec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 3 3 #marketing 10.160.50.13
+        infotec_IS2027 kurt 401 [22/Apr/2003:10:28:43 +0100] 4 3 #marketing 10.160.50.13
+        DigiMaster9110 boss 402 [22/Apr/2003:10:33:22 +0100] 1 440 finance-dep 10.160.51.33
+
+</pre><p>
+This was job ID &quot;401&quot;, printed on &quot;infotec_IS2027&quot; by user &quot;kurt&quot;, a
+64-page job printed in 3 copies and billed to &quot;#marketing&quot;, sent
+from IP address 10.160.50.13. The next job had ID &quot;402&quot;, was sent by
+user &quot;boss&quot; from IP address 10.160.51.33,printed from one page 440
+copies and is set to be billed to &quot;finance-dep&quot;.
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963765"></a>Possible Shortcomings</h3></div></div><div></div></div><p>
+What flaws or shortcomings are there with this quota system?
+</p><div class="itemizedlist"><ul type="disc"><li><p>the ones named above (wrongly logged job in case of
+printer hardware failure, etc.)</p></li><li><p>in reality, CUPS counts the job pages that are being
+processed in <span class="emphasis"><em>software</em></span> (that is, going through the
+&quot;RIP&quot;) rather than the physical sheets successfully leaving the
+printing device. Thus if there is a jam while printing the 5th sheet out
+of 1000 and the job is aborted by the printer, the &quot;page count&quot; will
+still show the figure of 1000 for that job</p></li><li><p>all quotas are the same for all users (no flexibility
+to give the boss a higher quota than the clerk) no support for
+groups</p></li><li><p>no means to read out the current balance or the
+&quot;used-up&quot; number of current quota</p></li><li><p>a user having used up 99 sheets of 100 quota will
+still be able to send and print a 1,000 sheet job</p></li><li><p>a user being denied a job because of a filled-up quota
+doesn't get a meaningful error message from CUPS other than
+&quot;client-error-not-possible&quot;.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963836"></a>Future Developments</h3></div></div><div></div></div><p>
+This is the best system currently available, and there are huge
+improvements under development for CUPS 1.2:
+</p><div class="itemizedlist"><ul type="disc"><li><p>page counting will go into the &quot;backends&quot; (these talk
+directly to the printer and will increase the count in sync with the
+actual printing process: thus a jam at the 5th sheet will lead to a
+stop in the counting)</p></li><li><p>quotas will be handled more flexibly</p></li><li><p>probably there will be support for users to inquire
+their &quot;accounts&quot; in advance</p></li><li><p>probably there will be support for some other tools
+around this topic</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2963884"></a>Other Accounting Tools</h3></div></div><div></div></div><p>
+PrintAnalyzer, pyKota, printbill, LogReport.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2963899"></a>Additional Material</h2></div></div><div></div></div><p>
+A printer queue with <span class="emphasis"><em>no</em></span> PPD associated to it is a
+&quot;raw&quot; printer and all files will go directly there as received by the
+spooler. The exceptions are file types &quot;application/octet-stream&quot;
+which need &quot;passthrough feature&quot; enabled. &quot;Raw&quot; 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 &quot;device URI&quot; notation: <tt class="filename">lpd://, socket://,
+smb://, ipp://, http://, parallel:/, serial:/, usb:/</tt> etc.)
+</p><p>
+&quot;cupsomatic&quot;/Foomatic are <span class="emphasis"><em>not</em></span> 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. &quot;cupsomatic&quot; is only a vehicle to execute a
+ghostscript commandline at that stage in the CUPS filtering chain,
+where &quot;normally&quot; the native CUPS &quot;pstoraster&quot; filter would kick
+in. cupsomatic by-passes pstoraster, &quot;kidnaps&quot; the printfile from CUPS
+away and re-directs it to go through Ghostscript. CUPS accepts this,
+because the associated CUPS-O-Matic-/Foomatic-PPD specifies:
+</p><pre class="screen">
+
+   *cupsFilter:  &quot;application/vnd.cups-postscript 0 cupsomatic&quot;
+
+</pre><p>
+This line persuades CUPS to hand the file to cupsomatic, once it has
+successfully converted it to the MIME type
+&quot;application/vnd.cups-postscript&quot;. This conversion will not happen for
+Jobs arriving from Windows which are auto-typed
+&quot;application/octet-stream&quot;, with the according changes in
+<tt class="filename">/etc/cups/mime.types</tt> in place.
+</p><p>
+CUPS is widely configurable and flexible, even regarding its filtering
+mechanism. Another workaround in some situations would be to have in
+<tt class="filename">/etc/cups/mime.types</tt> entries as follows:
+</p><pre class="screen">
+
+   application/postscript           application/vnd.cups-raw  0  -
+   application/vnd.cups-postscript  application/vnd.cups-raw  0  -
+
+</pre><p>
+This would prevent all Postscript files from being filtered (rather,
+they will through the virtual <span class="emphasis"><em>nullfilter</em></span>
+denoted with &quot;-&quot;).  This could only be useful for PS printers. If you
+want to print PS code on non-PS printers (provided they support ASCII
+text printing) an entry as follows could be useful:
+</p><pre class="screen">
+
+   */*           application/vnd.cups-raw  0  -
+
+</pre><p>
+and would effectively send <span class="emphasis"><em>all</em></span> files to the
+backend without further processing.
+</p><p>
+Lastly, you could have the following entry:
+</p><pre class="screen">
+
+   application/vnd.cups-postscript  application/vnd.cups-raw  0  my_PJL_stripping_filter
+
+</pre><p>
+You will need to write a <span class="emphasis"><em>my_PJL_stripping_filter</em></span>
+(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
+<tt class="filename">/usr/lib/cups/filters/</tt> and will be called by CUPS
+if it encounters a MIME type &quot;application/vnd.cups-postscript&quot;.
+</p><p>
+CUPS can handle <span class="emphasis"><em>-o job-hold-until=indefinite</em></span>.
+This keeps the job in the queue &quot;on hold&quot;. It will only be printed
+upon manual release by the printer operator. This is a requirement in
+many &quot;central reproduction departments&quot;, where a few operators manage
+the jobs of hundreds of users on some big machine, where no user is
+allowed to have direct access (such as when the operators often need
+to load the proper paper type before running the 10,000 page job
+requested by marketing for the mailing, etc.).
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2964092"></a>Auto-Deletion or Preservation of CUPS Spool Files</h2></div></div><div></div></div><p>
+Samba print files pass through two &quot;spool&quot; directories. One is the
+incoming directory managed by Samba, (set in the <span class="emphasis"><em>path =
+/var/spool/samba</em></span> directive in the
+<span class="emphasis"><em>[printers]</em></span> section of
+<tt class="filename">smb.conf</tt>). The other is the spool directory of
+your UNIX print subsystem. For CUPS it is normally
+<tt class="filename">/var/spool/cups/</tt>, as set by the cupsd.conf
+directive <tt class="filename">RequestRoot /var/spool/cups</tt>.
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964138"></a>CUPS Configuration Settings explained</h3></div></div><div></div></div><p>
+Some important parameter settings in the CUPS configuration file
+<tt class="filename">cupsd.conf</tt> are:
+</p><div class="variablelist"><dl><dt><span class="term">PreserveJobHistory Yes</span></dt><dd><p>
+This keeps some details of jobs in cupsd's mind (well it keeps the
+&quot;c12345&quot;, &quot;c12346&quot; etc. files in the CUPS spool directory, which do a
+similar job as the old-fashioned BSD-LPD control files). This is set
+to &quot;Yes&quot; as a default.
+</p></dd><dt><span class="term">PreserveJobFiles Yes</span></dt><dd><p>
+This keeps the job files themselves in cupsd's mind
+(well it keeps the &quot;d12345&quot;, &quot;d12346&quot; etc. files in the CUPS spool
+directory...). This is set to &quot;No&quot; as the CUPS
+default.
+</p></dd><dt><span class="term"><span class="emphasis"><em>&quot;MaxJobs 500&quot;</em></span></span></dt><dd><p>
+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.
+</p></dd></dl></div><p>
+(There are also additional settings for &quot;MaxJobsPerUser&quot; and
+&quot;MaxJobsPerPrinter&quot;...)
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964221"></a>Pre-conditions</h3></div></div><div></div></div><p>
+For everything to work as announced, you need to have three
+things:
+</p><div class="itemizedlist"><ul type="disc"><li><p>a Samba-smbd which is compiled against &quot;libcups&quot; (Check
+on Linux by running &quot;ldd `which smbd`&quot;)</p></li><li><p>a Samba-<tt class="filename">smb.conf</tt> setting of
+&quot;printing = cups&quot;</p></li><li><p>another Samba-<tt class="filename">smb.conf</tt> setting of
+&quot;printcap = cups&quot;</p></li></ul></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+In this case all other manually set printing-related commands (like
+&quot;print command&quot;, &quot;lpq command&quot;, &quot;lprm command&quot;, &quot;lppause command&quot; or
+&quot;lpresume command&quot;) are ignored and they should normally have no
+influence what-so-ever on your printing.
+</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964281"></a>Manual Configuration</h3></div></div><div></div></div><p>
+If you want to do things manually, replace the &quot;printing =
+cups&quot; by &quot;printing = bsd&quot;. Then your manually set commands may work
+(haven't tested this), and a &quot;print command = lp -d %P %s; rm %s&quot;
+may do what you need.
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2964299"></a>When <span class="emphasis"><em>not</em></span> to use Samba to print to
+CUPS</h2></div></div><div></div></div><p>
+[TO BE DONE]
+</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2964316"></a>In Case of Trouble.....</h2></div></div><div></div></div><p>
+If you have more problems, post the output of these commands
+to the CUPS or Samba mailing lists (choose the one which seems more
+relevant to your problem):
+</p><pre class="screen">
+
+   grep -v ^# /etc/cups/cupsd.conf | grep -v ^$
+   grep -v ^# /etc/samba/smb.conf | grep -v ^$ | grep -v &quot;^;&quot;
+
+</pre><p>
+(adapt paths as needed). These commands leave out the empty
+lines and lines with comments, providing the &quot;naked settings&quot; in a
+compact way. Don't forget to name the CUPS and Samba versions you
+are using! This saves bandwidth and makes for easier readability
+for experts (and you are expecting experts to read them, right?
+;-)
+</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964352"></a>Where to find Documentation</h3></div></div><div></div></div><p>
+[TO BE DONE]
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964364"></a>How to ask for Help</h3></div></div><div></div></div><p>
+[TO BE DONE]
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964377"></a>Where to find Help</h3></div></div><div></div></div><p>
+[TO BE DONE]
+</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2964391"></a>Appendix</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964398"></a>Printing <span class="emphasis"><em>from</em></span> CUPS to Windows attached
+Printers</h3></div></div><div></div></div><p>
+From time to time the question arises, how you can print
+<span class="emphasis"><em>to</em></span> a Windows attached printer
+<span class="emphasis"><em>from</em></span> Samba. Normally the local connection
+&quot;Windows host &lt;--&gt; printer&quot; would be done by USB or parallel
+cable, but this doesn't matter to Samba. From here only an SMB
+connection needs to be opened to the Windows host. Of course, this
+printer must be &quot;shared&quot; first. As you have learned by now, CUPS uses
+<span class="emphasis"><em>backends</em></span> to talk to printers and other
+servers. To talk to Windows shared printers you need to use the
+<span class="emphasis"><em>smb</em></span> (surprise, surprise!) backend. Check if this
+is in the CUPS backend directory. This resides usually in
+<tt class="filename">/usr/lib/cups/backend/</tt>. You need to find a &quot;smb&quot;
+file there. It should be a symlink to <tt class="filename">smbspool</tt>
+which file must exist and be executable:
+</p><pre class="screen">
+
+ # ls -l /usr/lib/cups/backend/   
+ total 253
+ drwxr-xr-x    3 root     root          720 Apr 30 19:04 .
+ drwxr-xr-x    6 root     root          125 Dec 19 17:13 ..
+ -rwxr-xr-x    1 root     root        10692 Feb 16 21:29 canon
+ -rwxr-xr-x    1 root     root        10692 Feb 16 21:29 epson
+ lrwxrwxrwx    1 root     root            3 Apr 17 22:50 http -&gt; ipp
+ -rwxr-xr-x    1 root     root        17316 Apr 17 22:50 ipp
+ -rwxr-xr-x    1 root     root        15420 Apr 20 17:01 lpd
+ -rwxr-xr-x    1 root     root         8656 Apr 20 17:01 parallel
+ -rwxr-xr-x    1 root     root         2162 Mar 31 23:15 pdfdistiller
+ lrwxrwxrwx    1 root     root           25 Apr 30 19:04 ptal -&gt; /usr/local/sbin/ptal-cups
+ -rwxr-xr-x    1 root     root         6284 Apr 20 17:01 scsi
+ lrwxrwxrwx    1 root     root           17 Apr  2 03:11 smb -&gt; /usr/bin/smbspool
+ -rwxr-xr-x    1 root     root         7912 Apr 20 17:01 socket
+ -rwxr-xr-x    1 root     root         9012 Apr 20 17:01 usb
+
+# ls -l `which smbspool`
+ -rwxr-xr-x    1 root     root       563245 Dec 28 14:49 /usr/bin/smbspool
+
+</pre><p>
+If this symlink doesn't exist, create it:
+</p><pre class="screen">
+
+# ln -s `which smbspool` /usr/lib/cups/backend/smb
+
+</pre><p>
+smbspool has been written by Mike Sweet from the CUPS folks.  It is
+included and ships with Samba. It may also be used with print
+subsystems other than CUPS, to spool jobs to Windows printer shares. To
+set up printer &quot;winprinter&quot; on CUPS, you need to have a &quot;driver&quot; for
+it. Essentially this means to convert the print data on the CUPS/Samba
+host to a format that the printer can digest (the Windows host is
+unable to convert any files you may send).  This also means you should
+be able to print to the printer if it were hooked directly at your
+Samba/CUPS host. For troubleshooting purposes, this is what you
+should do, to determine if that part of the process chain is in
+order. Then proceed to fix the network connection/authentication to
+the Windows host, etc.
+</p><p>
+To install a printer with the smb backend on CUPS, use this command:
+</p><pre class="screen">
+
+# lpadmin -p winprinter -v smb://WINDOWSNETBIOSNAME/printersharename -P /path/to/PPD
+
+</pre><p>
+The <span class="emphasis"><em>PPD</em></span> must be able to direct CUPS to generate
+the print data for the target model. For PostScript printers just use
+the PPD that would be used with the Windows NT PostScript driver. But
+what can you do if the printer is only accessible with a password? Or
+if the printer's host is part of another workgroup? This is provided
+for: you can include the required parameters as part of the
+<tt class="filename">smb://</tt> device-URI. Like this:
+</p><pre class="screen">
+
+ smb://WORKGROUP/WINDOWSNETBIOSNAME/printersharename 
+ smb://username:password@WORKGROUP/WINDOWSNETBIOSNAME/printersharename
+ smb://username:password@WINDOWSNETBIOSNAME/printersharename
+
+</pre><p>
+Note that the device-URI will be visible in the process list of the
+Samba server (e.g. when someone uses the <b class="command">ps -aux</b>
+command on Linux), even if the username and passwords are sanitized
+before they get written into the log files.  So this is an inherently
+insecure option. However it is the only one. Don't use it if you want
+to protect your passwords. Better share the printer in a way that
+doesn't require a password! Printing will only work if you have a
+working netbios name resolution up and running. Note that this is a
+feature of CUPS and you don't necessarily need to have smbd running
+(but who wants that? :-).
+</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2964612"></a>More CUPS filtering Chains</h3></div></div><div></div></div><p>
+The following diagrams reveal how CUPS handles print jobs.
+</p><pre class="screen">
+#########################################################################
+#
+# 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):
+#
+# SOMETHNG-FILEFORMAT
+#      |
+#      V
+#     somethingtops
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      V
+#     pstops
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT
+#      |
+#      V
+#     pstoraster   # as shipped with CUPS, independent from any Ghostscipt
+#      |           # installation on the system
+#      |  (= &quot;postscipt interpreter&quot;)
+#      V
+# APPLICATION/VND.CUPS-RASTER
+#      |
+#      V
+#     rastertosomething  (e.g. Gimp-Print filters may be plugged in here)
+#      |   (= &quot;raster driver&quot;)
+#      V
+# SOMETHING-DEVICE-SPECIFIC
+#      |
+#      V
+#     backend
+#
+#
+# ESP PrintPro has some enhanced &quot;rastertosomething&quot; filters as compared to
+# CUPS, and also a somewhat improved &quot;pstoraster&quot; filter.
+#
+# NOTE: Gimp-Print and some other 3rd-Party-Filters (like TurboPrint) to
+#       CUPS and ESP PrintPro plug-in where rastertosomething is noted.
+#
+#########################################################################
+</pre><pre class="screen">
+#########################################################################
+#
+# This is how &quot;cupsomatic&quot; comes into play:
+# =========================================
+#
+# SOMETHNG-FILEFORMAT
+#      |
+#      V
+#    somethingtops
+#      |
+#      V
+# APPLICATION/POSTSCRIPT
+#      |
+#      V
+#    pstops
+#      |
+#      V
+# APPLICATION/VND.CUPS-POSTSCRIPT ----------------+
+#      |                                          V
+#      V                                         cupsomatic
+#    pstoraster                                  (constructs complicated
+#      |  (= &quot;postscipt interpreter&quot;)            Ghostscript commandline
+#      |                                         to let the file be
+#      V                                         processed by a
+# APPLICATION/VND.CUPS-RASTER                    &quot;-sDEVICE=s.th.&quot;
+#      |                                         call...)
+#      V                                          |
+#    rastertosomething                            V
+#      |    (= &quot;raster driver&quot;)     +-------------------------+
+#      |                            | Ghostscript at