diff options
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/CodingSuggestions.xml (renamed from docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml) | 14 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/Tracing.xml (renamed from docs-xml/Samba3-Developers-Guide/Tracing.xml) | 12 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/architecture.xml (renamed from docs-xml/Samba3-Developers-Guide/architecture.xml) | 8 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/cifsntdomain.xml (renamed from docs-xml/Samba3-Developers-Guide/cifsntdomain.xml) | 14 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/contributing.xml (renamed from docs-xml/Samba3-Developers-Guide/contributing.xml) | 66 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/debug.xml (renamed from docs-xml/Samba3-Developers-Guide/debug.xml) | 2 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/encryption.xml (renamed from docs-xml/Samba3-Developers-Guide/encryption.xml) | 160 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/gencache.xml (renamed from docs-xml/Samba3-Developers-Guide/gencache.xml) | 0 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/index.xml (renamed from docs-xml/Samba3-Developers-Guide/index.xml) | 18 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/internals.xml (renamed from docs-xml/Samba3-Developers-Guide/internals.xml) | 50 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/modules.xml (renamed from docs-xml/Samba3-Developers-Guide/modules.xml) | 60 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/packagers.xml (renamed from docs-xml/Samba3-Developers-Guide/packagers.xml) | 2 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/parsing.xml (renamed from docs-xml/Samba3-Developers-Guide/parsing.xml) | 4 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/printing.xml (renamed from docs-xml/Samba3-Developers-Guide/printing.xml) | 16 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/rpc_plugin.xml (renamed from docs-xml/Samba3-Developers-Guide/rpc_plugin.xml) | 6 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/unix-smb.xml (renamed from docs-xml/Samba3-Developers-Guide/unix-smb.xml) | 15 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/vfs.xml (renamed from docs-xml/Samba3-Developers-Guide/vfs.xml) | 96 | ||||
| -rw-r--r-- | docs-xml/Samba-Developers-Guide/wins.xml (renamed from docs-xml/Samba3-Developers-Guide/wins.xml) | 20 | ||||
| -rw-r--r-- | docs-xml/htmldocs.html | 2 |
19 files changed, 282 insertions, 283 deletions
diff --git a/docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml b/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml index caf93d84ad0..5e44d030812 100644 --- a/docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml +++ b/docs-xml/Samba-Developers-Guide/CodingSuggestions.xml @@ -34,7 +34,7 @@ document will attempt to document a few of the more important coding practices used at this time on the Samba project. The coding practices are expected to change slightly over time, and even to grow as more is learned about obscure portability considerations. Two existing documents -<filename>samba/source/internals.doc</filename> and +<filename>samba/source/internals.doc</filename> and <filename>samba/source/architecture.doc</filename> provide additional information. </para> @@ -84,7 +84,7 @@ Here are some other suggestions: <listitem><para> use d_printf instead of printf for display text - reason: enable auto-substitution of translated language text + reason: enable auto-substitution of translated language text </para></listitem> <listitem><para> @@ -115,7 +115,7 @@ Here are some other suggestions: <listitem><para> when passing a va_list as an arg, or assigning one to another please use the VA_COPY() macro - reason: on some platforms, va_list is a struct that must be + reason: on some platforms, va_list is a struct that must be initialized in each function...can SEGV if you don't. </para></listitem> @@ -125,13 +125,13 @@ Here are some other suggestions: </para></listitem> <listitem><para> - don't explicitly include new header files in C files - new h files + don't explicitly include new header files in C files - new h files should be included by adding them once to includes.h reason: consistency </para></listitem> <listitem><para> - don't explicitly extern functions (they are autogenerated by + don't explicitly extern functions (they are autogenerated by "make proto" into proto.h) reason: consistency </para></listitem> @@ -219,13 +219,13 @@ Here are some other suggestions: for fragile, hand to maintain code. Instead, design an interface and use tables containing function pointers to implement specific functionality. This is particularly important for command - interpreters. + interpreters. </para></listitem> <listitem><para> Think carefully about what it will be like for someone else to add to and maintain your code. If it would be hard for someone else to - maintain then do it another way. + maintain then do it another way. </para></listitem> </orderedlist> diff --git a/docs-xml/Samba3-Developers-Guide/Tracing.xml b/docs-xml/Samba-Developers-Guide/Tracing.xml index 3eaab6373ec..23b46d5381b 100644 --- a/docs-xml/Samba3-Developers-Guide/Tracing.xml +++ b/docs-xml/Samba-Developers-Guide/Tracing.xml @@ -29,14 +29,14 @@ that they nearly all come with a system trace utility that allows you to monitor all system calls that a program is making. This is extremely using for debugging and also helps when trying to work out why something is slower than you expect. You can use system tracing -without any special compilation options. +without any special compilation options. </para> <para> The system trace utility is called different things on different systems. On Linux systems its called strace. Under SunOS 4 its called trace. Under SVR4 style systems (including solaris) its called -truss. Under many BSD systems its called ktrace. +truss. Under many BSD systems its called ktrace. </para> <para> @@ -52,7 +52,7 @@ Next, try using strace on some simple commands. For example, <command>strace ls</command> or <command>strace echo hello</command>. </para> -<para> +<para> You'll notice that it produces a LOT of output. It is showing you the arguments to every system call that the program makes and the result. Very little happens in a program without a system call so you @@ -98,7 +98,7 @@ forks. This is great for finding printing problems caused by the <para> Once you are attached you then can do whatever it is on the client that is causing problems and you will capture all the system calls -that smbd makes. +that smbd makes. </para> <para> @@ -123,8 +123,8 @@ causes printing to fail with Samba: </programlisting></para> <para> -The process is trying to first open <filename>/dev/null</filename> read-write -then read-only. Both fail. This means <filename>/dev/null</filename> has +The process is trying to first open <filename>/dev/null</filename> read-write +then read-only. Both fail. This means <filename>/dev/null</filename> has incorrect permissions. </para> diff --git a/docs-xml/Samba3-Developers-Guide/architecture.xml b/docs-xml/Samba-Developers-Guide/architecture.xml index bb0f29981b4..1ad69935094 100644 --- a/docs-xml/Samba3-Developers-Guide/architecture.xml +++ b/docs-xml/Samba-Developers-Guide/architecture.xml @@ -18,7 +18,7 @@ This document gives a general overview of how Samba works internally. The Samba Team has tried to come up with a model which is the best possible compromise between elegance, portability, security and the constraints imposed by the very messy SMB and CIFS -protocol. +protocol. </para> <para> @@ -45,7 +45,7 @@ It also tries to answer some of the frequently asked questions such as: <para> People sometimes tout threads as a uniformly good thing. They are very nice in their place but are quite inappropriate for smbd. nmbd is -another matter, and multi-threading it would be very nice. +another matter, and multi-threading it would be very nice. </para> <para> @@ -90,7 +90,7 @@ A few problems that would arise from a threaded smbd are: many of the system calls we make are blocking. Non-blocking equivalents of many calls are either not available or are awkward (and slow) to use. So while we block in one thread all clients are - waiting. Imagine if one share is a slow NFS filesystem and the others + waiting. Imagine if one share is a slow NFS filesystem and the others are fast, we will end up slowing all clients to the speed of NFS. </para></listitem> @@ -179,7 +179,7 @@ wire. It's a nice format that is very amenable to processing but still keeps the idea of a distinct packet. See "struct packet_struct" in nameserv.h. It has all the detail but none of the on-the-wire mess. This makes it ideal for using in disk or memory-based databases -for browsing and WINS support. +for browsing and WINS support. </para> </sect1> diff --git a/docs-xml/Samba3-Developers-Guide/cifsntdomain.xml b/docs-xml/Samba-Developers-Guide/cifsntdomain.xml index 8467a6f5352..a302fb15c17 100644 --- a/docs-xml/Samba3-Developers-Guide/cifsntdomain.xml +++ b/docs-xml/Samba-Developers-Guide/cifsntdomain.xml @@ -48,7 +48,7 @@ instructive than this document. </para> <para> -Also needed, to fully implement NT Domain Login Services, is the +Also needed, to fully implement NT Domain Login Services, is the document describing the cryptographic part of the NT authentication. This document is available from comp.protocols.smb; from the ntsecurity.net digest and from the samba digest, amongst other sources. @@ -79,7 +79,7 @@ achieved by setting the following REG_SZ registry key to 0x1ffffff: <para><filename>HKLM\SYSTEM\CurrentControlSet\Services\Netlogon\Parameters</filename></para> <para><emphasis>Incorrect direct editing of the registry can cause your -machine to fail. Then again, so can incorrect implementation of this +machine to fail. Then again, so can incorrect implementation of this protocol. See "Liability:" above.</emphasis></para> <para> @@ -103,11 +103,11 @@ include, but are not limited to: <listitem><para>The exact meaning/definition of various magic constants or enumerations.</para></listitem> <listitem><para>The reply error code and use of that error code when a -workstation becomes a member of a domain (to be described later). -Failure to return this error code will make the workstation report +workstation becomes a member of a domain (to be described later). +Failure to return this error code will make the workstation report that it is already a member of the domain.</para></listitem> -<listitem><para>the cryptographic side of the NetrServerPasswordSet command, +<listitem><para>the cryptographic side of the NetrServerPasswordSet command, which would allow the workstation to change its password. This password is used to generate the long-term session key. [It is possible to reject this command, and keep the default workstation password].</para></listitem> @@ -129,7 +129,7 @@ command, and keep the default workstation password].</para></listitem> <sect2> <title>Credits</title> -<simplelist> +<simplelist> <member>Paul Ashton: loads of work with Net Monitor; understanding the NT authentication system; reference implementation of the NT domain support on which this document is originally based.</member> <member>Duncan Stansfield: low-level analysis of MSRPC Pipes.</member> <member>Linus Nordberg: producing c-code from Paul's crypto spec.</member> @@ -1226,7 +1226,7 @@ appears a third time after the last sub-structure. <title>MSRPC Pipes</title> <para> -The MSRPC is conducted over an SMB Transact Pipe with a name of +The MSRPC is conducted over an SMB Transact Pipe with a name of <filename>\PIPE\</filename>. You must first obtain a 16 bit file handle, by sending a SMBopenX with the pipe name <filename>\PIPE\srvsvc</filename> for example. You can then perform an SMB Trans, diff --git a/docs-xml/Samba3-Developers-Guide/contributing.xml b/docs-xml/Samba-Developers-Guide/contributing.xml index 61612d708d5..af21b6e13e1 100644 --- a/docs-xml/Samba3-Developers-Guide/contributing.xml +++ b/docs-xml/Samba-Developers-Guide/contributing.xml @@ -8,8 +8,8 @@ <title>Contributing code</title> -<para>Here are a few tips and notes that might be useful if you are - interested in modifying samba source code and getting it into +<para>Here are a few tips and notes that might be useful if you are + interested in modifying samba source code and getting it into samba's main branch.</para> <variablelist> @@ -17,8 +17,8 @@ <term>Retrieving the source</term> <listitem> - <para>In order to contribute code to samba, make sure you have the - latest source. Retrieving the samba source code from CVS is + <para>In order to contribute code to samba, make sure you have the + latest source. Retrieving the samba source code from CVS is documented in the appendix of the Samba HOWTO Collection. </para> </listitem> @@ -27,15 +27,15 @@ <varlistentry> <term>Discuss large modifications with team members</term> <listitem> - <para>Please discuss large modifications you are going to make - with members of the samba team. Some parts of the samba code - have one or more 'owners' - samba developers who wrote most - of the code and maintain it. + <para>Please discuss large modifications you are going to make + with members of the samba team. Some parts of the samba code + have one or more 'owners' - samba developers who wrote most + of the code and maintain it. </para> - <para>This way you can avoid spending your time and effort on - something that is not going to make it into the main samba branch - because someone else was working on the same thing or because your + <para>This way you can avoid spending your time and effort on + something that is not going to make it into the main samba branch + because someone else was working on the same thing or because your implementation is not the correct one. </para> </listitem> @@ -44,13 +44,13 @@ <varlistentry> <term>Patch format</term> <listitem> - <para>Patches to the samba tree should be in unified diff format, - e.g. files generated by <userinput>diff -u</userinput>. + <para>Patches to the samba tree should be in unified diff format, + e.g. files generated by <userinput>diff -u</userinput>. </para> - <para>If you are modifying a copy of samba you retrieved from CVS, - you can easily generate a diff file of these changes by running - <userinput>cvs diff -u</userinput>.</para> + <para>If you are modifying a copy of samba you retrieved from CVS, + you can easily generate a diff file of these changes by running + <userinput>cvs diff -u</userinput>.</para> </listitem> </varlistentry> @@ -59,17 +59,17 @@ <listitem><para> <itemizedlist> <listitem><para>Don't simply copy code from other places and modify it until it - works. Code needs to be clean and logical. Duplicate + works. Code needs to be clean and logical. Duplicate code is to be avoided.</para></listitem> - <listitem><para>Test your patch. It might take a while before one of us looks - at your patch so it will take longer before your patch when your patch + <listitem><para>Test your patch. It might take a while before one of us looks + at your patch so it will take longer before your patch when your patch needs to go thru the review cycle again.</para></listitem> - <listitem><para>Don't put separate patches in one large diff file. This makes - it harder to read, understand and test the patch. You might - also risk not getting a good patch committed because you mixed it + <listitem><para>Don't put separate patches in one large diff file. This makes + it harder to read, understand and test the patch. You might + also risk not getting a good patch committed because you mixed it with one that had issues. </para></listitem> - <listitem><para>Make sure your patch complies to the samba coding style as - suggested in the coding-suggestions chapter. </para></listitem> + <listitem><para>Make sure your patch complies to the samba coding style as + suggested in the coding-suggestions chapter. </para></listitem> </itemizedlist> </para> </listitem> @@ -79,7 +79,7 @@ <term>Sending in bugfixes</term> <listitem> <para>Bugfixes to bugs in samba should be submitted to samba's - <ulink url="https://bugzilla.samba.org/">bugzilla system</ulink>, + <ulink url="https://bugzilla.samba.org/">bugzilla system</ulink>, along with a description of the bug. </para> </listitem> @@ -88,12 +88,12 @@ <varlistentry> <term>Sending in feature patches</term> <listitem> - <para>Send feature patches along with a description of what the - patch is supposed to do to the + <para>Send feature patches along with a description of what the + patch is supposed to do to the <ulink url="mailto:samba-technical@lists.samba.org">Samba-technical mailinglist</ulink> and possibly to a samba team member who is (one of the) 'owners' - of the code you made modifications to. We are all busy people - so everybody tends to 'let one of the others handle it'. If nobody - responded to your patch for a week, try to send it again until you + of the code you made modifications to. We are all busy people + so everybody tends to 'let one of the others handle it'. If nobody + responded to your patch for a week, try to send it again until you get a response from one of us. </para></listitem> </varlistentry> @@ -101,9 +101,9 @@ <varlistentry> <term>Feedback on your patch</term> <listitem> - <para>One of the team members will look at your patch and either - commit your patch or give comments why he won't apply it. In the - latter case you can fix your patch and re-send it until + <para>One of the team members will look at your patch and either + commit your patch or give comments why he won't apply it. In the + latter case you can fix your patch and re-send it until your patch is approved.</para> </listitem> </varlistentry> diff --git a/docs-xml/Samba3-Developers-Guide/debug.xml b/docs-xml/Samba-Developers-Guide/debug.xml index a55facedff4..50a363c7cf3 100644 --- a/docs-xml/Samba3-Developers-Guide/debug.xml +++ b/docs-xml/Samba-Developers-Guide/debug.xml @@ -287,7 +287,7 @@ input is printed into a buffer using the vslprintf() function, and then passed to format_debug_text(). If you use DEBUGLVL() you will probably print the body of the -message using dbgtext(). +message using dbgtext(). </para> </sect2> diff --git a/docs-xml/Samba3-Developers-Guide/encryption.xml b/docs-xml/Samba-Developers-Guide/encryption.xml index a4405a9343d..cba94904ea5 100644 --- a/docs-xml/Samba3-Developers-Guide/encryption.xml +++ b/docs-xml/Samba-Developers-Guide/encryption.xml @@ -16,92 +16,92 @@ <pubdate>19 Apr 1999</pubdate> </chapterinfo> - + <title>LanMan and NT Password Encryption</title> <sect1> <title>Introduction</title> - - <para>With the development of LanManager and Windows NT - compatible password encryption for Samba, it is now able - to validate user connections in exactly the same way as + + <para>With the development of LanManager and Windows NT + compatible password encryption for Samba, it is now able + to validate user connections in exactly the same way as a LanManager or Windows NT server.</para> - <para>This document describes how the SMB password encryption - algorithm works and what issues there are in choosing whether - you want to use it. You should read it carefully, especially + <para>This document describes how the SMB password encryption + algorithm works and what issues there are in choosing whether + you want to use it. You should read it carefully, especially the part about security and the "PROS and CONS" section.</para> - + </sect1> <sect1> <title>How does it work?</title> - <para>LanManager encryption is somewhat similar to UNIX - password encryption. The server uses a file containing a - hashed value of a user's password. This is created by taking - the user's plaintext password, capitalising it, and either - truncating to 14 bytes or padding to 14 bytes with null bytes. - This 14 byte value is used as two 56 bit DES keys to encrypt - a 'magic' eight byte value, forming a 16 byte value which is - stored by the server and client. Let this value be known as + <para>LanManager encryption is somewhat similar to UNIX + password encryption. The server uses a file containing a + hashed value of a user's password. This is created by taking + the user's plaintext password, capitalising it, and either + truncating to 14 bytes or padding to 14 bytes with null bytes. + This 14 byte value is used as two 56 bit DES keys to encrypt + a 'magic' eight byte value, forming a 16 byte value which is + stored by the server and client. Let this value be known as the "hashed password".</para> - - <para>Windows NT encryption is a higher quality mechanism, - consisting of doing an MD4 hash on a Unicode version of the user's - password. This also produces a 16 byte hash value that is + + <para>Windows NT encryption is a higher quality mechanism, + consisting of doing an MD4 hash on a Unicode version of the user's + password. This also produces a 16 byte hash value that is non-reversible.</para> - <para>When a client (LanManager, Windows for WorkGroups, Windows - 95 or Windows NT) wishes to mount a Samba drive (or use a Samba - resource), it first requests a connection and negotiates the - protocol that the client and server will use. In the reply to this - request the Samba server generates and appends an 8 byte, random - value - this is stored in the Samba server after the reply is sent - and is known as the "challenge". The challenge is different for + <para>When a client (LanManager, Windows for WorkGroups, Windows + 95 or Windows NT) wishes to mount a Samba drive (or use a Samba + resource), it first requests a connection and negotiates the + protocol that the client and server will use. In the reply to this + request the Samba server generates and appends an 8 byte, random + value - this is stored in the Samba server after the reply is sent + and is known as the "challenge". The challenge is different for every client connection.</para> - <para>The client then uses the hashed password (16 byte values - described above), appended with 5 null bytes, as three 56 bit - DES keys, each of which is used to encrypt the challenge 8 byte + <para>The client then uses the hashed password (16 byte values + described above), appended with 5 null bytes, as three 56 bit + DES keys, each of which is used to encrypt the challenge 8 byte value, forming a 24 byte value known as the "response".</para> - <para>In the SMB call SMBsessionsetupX (when user level security - is selected) or the call SMBtconX (when share level security is - selected), the 24 byte response is returned by the client to the - Samba server. For Windows NT protocol levels the above calculation - is done on both hashes of the user's password and both responses are + <para>In the SMB call SMBsessionsetupX (when user level security + is selected) or the call SMBtconX (when share level security is + selected), the 24 byte response is returned by the client to the + Samba server. For Windows NT protocol levels the above calculation + is done on both hashes of the user's password and both responses are returned in the SMB call, giving two 24 byte values.</para> - <para>The Samba server then reproduces the above calculation, using - its own stored value of the 16 byte hashed password (read from the - <filename>smbpasswd</filename> file - described later) and the challenge - value that it kept from the negotiate protocol reply. It then checks - to see if the 24 byte value it calculates matches the 24 byte value + <para>The Samba server then reproduces the above calculation, using + its own stored value of the 16 byte hashed password (read from the + <filename>smbpasswd</filename> file - described later) and the challenge + value that it kept from the negotiate protocol reply. It then checks + to see if the 24 byte value it calculates matches the 24 byte value returned to it from the client.</para> - <para>If these values match exactly, then the client knew the - correct password (or the 16 byte hashed value - see security note - below) and is thus allowed access. If not, then the client did not + <para>If these values match exactly, then the client knew the + correct password (or the 16 byte hashed value - see security note + below) and is thus allowed access. If not, then the client did not know the correct password and is denied access.</para> - <para>Note that the Samba server never knows or stores the cleartext - of the user's password - just the 16 byte hashed values derived from - it. Also note that the cleartext password or 16 byte hashed values + <para>Note that the Samba server never knows or stores the cleartext + of the user's password - just the 16 byte hashed values derived from + it. Also note that the cleartext password or 16 byte hashed values are never transmitted over the network - thus increasing security.</para> </sect1> <sect1> <title>The smbpasswd file</title> <anchor id="SMBPASSWDFILEFORMAT"/> - <para>In order for Samba to participate in the above protocol + <para>In order for Samba to participate in the above protocol it must be able to look up the 16 byte hashed values given a user name. Unfortunately, as the UNIX password value is also a one way hash function (ie. it is impossible to retrieve the cleartext of the user's password given the UNIX hash of it), a separate password file containing this 16 byte value must be kept. To minimise problems with these two password files, getting out of sync, the UNIX <filename> - /etc/passwd</filename> and the <filename>smbpasswd</filename> file, + /etc/passwd</filename> and the <filename>smbpasswd</filename> file, a utility, <command>mksmbpasswd.sh</command>, is provided to generate a smbpasswd file from a UNIX <filename>/etc/passwd</filename> file. </para> @@ -109,52 +109,52 @@ <para>To generate the smbpasswd file from your <filename>/etc/passwd </filename> file use the following command:</para> - + <para><prompt>$ </prompt><userinput>cat /etc/passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd</userinput></para> - + <para>If you are running on a system that uses NIS, use</para> <para><prompt>$ </prompt><userinput>ypcat passwd | mksmbpasswd.sh > /usr/local/samba/private/smbpasswd</userinput></para> - - <para>The <command>mksmbpasswd.sh</command> program is found in - the Samba source directory. By default, the smbpasswd file is + + <para>The <command>mksmbpasswd.sh</command> program is found in + the Samba source directory. By default, the smbpasswd file is stored in :</para> <para><filename>/usr/local/samba/private/smbpasswd</filename></para> - <para>The owner of the <filename>/usr/local/samba/private/</filename> - directory should be set to root, and the permissions on it should + <para>The owner of the <filename>/usr/local/samba/private/</filename> + directory should be set to root, and the permissions on it should be set to 0500 (<command>chmod 500 /usr/local/samba/private</command>). </para> - <para>Likewise, the smbpasswd file inside the private directory should + <para>Likewise, the smbpasswd file inside the private directory should be owned by root and the permissions on is should be set to 0600 (<command>chmod 600 smbpasswd</command>).</para> - <para>The format of the smbpasswd file is (The line has been - wrapped here. It should appear as one entry per line in + <para>The format of the smbpasswd file is (The line has been + wrapped here. It should appear as one entry per line in your smbpasswd file.)</para> - + <para><programlisting> username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: [Account type]:LCT-<last-change-time>:Long name </programlisting></para> - - <para>Although only the <replaceable>username</replaceable>, + + <para>Although only the <replaceable>username</replaceable>, <replaceable>uid</replaceable>, <replaceable> XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</replaceable>, [<replaceable>Account type</replaceable>] and <replaceable> - last-change-time</replaceable> sections are significant + last-change-time</replaceable> sections are significant and are looked at in the Samba code.</para> - <para>It is <emphasis>VITALLY</emphasis> important that there by 32 - 'X' characters between the two ':' characters in the XXX sections - - the smbpasswd and Samba code will fail to validate any entries that - do not have 32 characters between ':' characters. The first XXX - section is for the Lanman password hash, the second is for the + <para>It is <emphasis>VITALLY</emphasis> important that there by 32 + 'X' characters between the two ':' characters in the XXX sections - + the smbpasswd and Samba code will fail to validate any entries that + do not have 32 characters between ':' characters. The first XXX + section is for the Lanman password hash, the second is for the Windows NT version.</para> <para>When the password file is created all users have password entries @@ -167,32 +167,32 @@ username:uid:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: using vi, and replace the first 11 characters with the ascii text <constant>"NO PASSWORD"</constant> (minus the quotes).</para> - <para>For example, to clear the password for user bob, his smbpasswd file + <para>For example, to clear the password for user bob, his smbpasswd file entry would look like :</para> <para><programlisting> bob:100:NO PASSWORDXXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX: [U ]:LCT-00000000:Bob's full name:/bobhome:/bobshell </programlisting></para> - - <para>If you are allowing users to use the smbpasswd command to set - their own passwords, you may want to give users NO PASSWORD initially - so they do not have to enter a previous password when changing to their + + <para>If you are allowing users to use the smbpasswd command to set + their own passwords, you may want to give users NO PASSWORD initially + so they do not have to enter a previous password when changing to their new password (not recommended). In order for you to allow this the - <command>smbpasswd</command> program must be able to connect to the - <command>smbd</command> daemon as that user with no password. Enable this + <command>smbpasswd</command> program must be able to connect to the + <command>smbd</command> daemon as that user with no password. Enable this by adding the line :</para> <para><command>null passwords = yes</command></para> - - <para>to the [global] section of the smb.conf file (this is why + + <para>to the [global] section of the smb.conf file (this is why the above scenario is not recommended). Preferably, allocate your users a default password to begin with, so you do not have to enable this on your server.</para> - <para><emphasis>Note : </emphasis>This file should be protected very - carefully. Anyone with access to this file can (with enough knowledge of - the protocols) gain access to your SMB server. The file is thus more + <para><emphasis>Note : </emphasis>This file should be protected very + carefully. Anyone with access to this file can (with enough knowledge of + the protocols) gain access to your SMB server. The file is thus more sensitive than a normal unix <filename>/etc/passwd</filename> file.</para> </sect1> diff --git a/docs-xml/Samba3-Developers-Guide/gencache.xml b/docs-xml/Samba-Developers-Guide/gencache.xml index 7e8475c192b..7e8475c192b 100644 --- a/docs-xml/Samba3-Developers-Guide/gencache.xml +++ b/docs-xml/Samba-Developers-Guide/gencache.xml diff --git a/docs-xml/Samba3-Developers-Guide/index.xml b/docs-xml/Samba-Developers-Guide/index.xml index 503fd22c111..5126292c138 100644 --- a/docs-xml/Samba3-Developers-Guide/index.xml +++ b/docs-xml/Samba-Developers-Guide/index.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE book PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc" [ -<!ATTLIST book +<!ATTLIST book xmlns:xi CDATA #FIXED "http://www.w3.org/2003/XInclude"> ]> @@ -13,30 +13,30 @@ <authorgroup> <editor>&person.jelmer;</editor> </authorgroup> - + <abstract> <para> <emphasis>Last Update</emphasis> : Fri Oct 10 00:59:58 CEST 2003 </para> <para> -This book is a collection of documents that might be useful for +This book is a collection of documents that might be useful for people developing samba or those interested in doing so. -It's nothing more than a collection of documents written by samba developers about +It's nothing more than a collection of documents written by samba developers about the internals of various parts of samba and the SMB protocol. It's still (and will always be) incomplete. The most recent version of this document can be found at <ulink url="http://devel.samba.org/">http://devel.samba.org/</ulink>. </para> <para> -This documentation is distributed under the GNU General Public License (GPL) +This documentation is distributed under the GNU General Public License (GPL) version 2. A copy of the license is included with the Samba source -distribution. A copy can be found on-line at <ulink +distribution. A copy can be found on-line at <ulink url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</ulink> </para> <para><warning> - This document is incomplete and unmaintained. It is merely a + This document is incomplete and unmaintained. It is merely a collection of development-related notes. </warning></para> @@ -44,7 +44,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u </bookinfo> -<xi:include href="../Samba3-Developers-Guide-attributions.xml"> +<xi:include href="../Samba-Developers-Guide-attributions.xml"> <xi:fallback/> </xi:include> @@ -76,7 +76,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u <part> <title>Samba Subsystems</title> - + <xi:include href="rpc_plugin.xml"/> <xi:include href="vfs.xml"/> <xi:include href="parsing.xml"/> diff --git a/docs-xml/Samba3-Developers-Guide/internals.xml b/docs-xml/Samba-Developers-Guide/internals.xml index bd9eaac802a..4368e181d9d 100644 --- a/docs-xml/Samba3-Developers-Guide/internals.xml +++ b/docs-xml/Samba-Developers-Guide/internals.xml @@ -41,7 +41,7 @@ The new system works like this: <listitem><para> all char* strings inside Samba are "unix" strings. These are multi-byte strings that are in the charset defined by the "unix - charset" option in smb.conf. + charset" option in smb.conf. </para></listitem> <listitem><para> @@ -49,7 +49,7 @@ The new system works like this: character set that is used does need the following properties: </para> <orderedlist> - + <listitem><para> must not contain NULLs except for termination </para></listitem> @@ -57,9 +57,9 @@ The new system works like this: <listitem><para> must be 7-bit compatible with C strings, so that a constant string or character in C will be byte-for-byte identical to the - equivalent string in the chosen character set. + equivalent string in the chosen character set. </para></listitem> - + <listitem><para> when you uppercase or lowercase a string it does not become longer than the original string @@ -70,7 +70,7 @@ The new system works like this: will throw at it </para></listitem> </orderedlist> - + <para> For example, UTF-8 is fine, and most multi-byte asian character sets are fine, but UCS2 could not be used for unix strings as they @@ -84,7 +84,7 @@ The new system works like this: compatible with the clients character set then you need to use a pull_ or push_ function. The pull_ functions pull a string from a wire buffer into a (multi-byte) unix string. The push_ functions - push a string out to a wire buffer. + push a string out to a wire buffer. </para></listitem> <listitem><para> @@ -99,7 +99,7 @@ The new system works like this: functions clistr_ and srvstr_ that call the pull_/push_ functions with the appropriate first argument. </para> - + <para> You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2 functions if you know that a particular string is ascii or @@ -136,7 +136,7 @@ The new system works like this: <title>Macros in byteorder.h</title> <para> -This section describes the macros defined in byteorder.h. These macros +This section describes the macros defined in byteorder.h. These macros are used extensively in the Samba code. </para> @@ -161,7 +161,7 @@ returns the byte at offset pos within buffer buf as an unsigned character. <sect2> <title>SVAL(buf,pos)</title> <para> - returns the value of the unsigned short (16 bit) little-endian integer at + returns the value of the unsigned short (16 bit) little-endian integer at offset pos within buffer buf. An integer of this type is sometimes refered to as "USHORT". </para> @@ -169,13 +169,13 @@ returns the byte at offset pos within buffer buf as an unsigned character. <sect2> <title>IVAL(buf,pos)</title> -<para>returns the value of the unsigned 32 bit little-endian integer at offset +<para>returns the value of the unsigned 32 bit little-endian integer at offset pos within buffer buf.</para> </sect2> <sect2> <title>SVALS(buf,pos)</title> -<para>returns the value of the signed short (16 bit) little-endian integer at +<para>returns the value of the signed short (16 bit) little-endian integer at offset pos within buffer buf.</para> </sect2> @@ -187,19 +187,19 @@ within buffer buf.</para> <sect2> <title>SSVAL(buf,pos,val)</title> -<para>sets the unsigned short (16 bit) little-endian integer at offset pos within +<para>sets the unsigned short (16 bit) little-endian integer at offset pos within buffer buf to value val.</para> </sect2> <sect2> <title>SIVAL(buf,pos,val)</title> -<para>sets the unsigned 32 bit little-endian integer at offset pos within buffer +<para>sets the unsigned 32 bit little-endian integer at offset pos within buffer buf to the value val.</para> </sect2> <sect2> <title>SSVALS(buf,pos,val)</title> -<para>sets the short (16 bit) signed little-endian integer at offset pos within +<para>sets the short (16 bit) signed little-endian integer at offset pos within buffer buf to the value val.</para> </sect2> @@ -211,26 +211,26 @@ buf to the value val.</para> <sect2> <title>RSVAL(buf,pos)</title> -<para>returns the value of the unsigned short (16 bit) big-endian integer at +<para>returns the value of the unsigned short (16 bit) big-endian integer at offset pos within buffer buf.</para> </sect2> <sect2> <title>RIVAL(buf,pos)</title> -<para>returns the value of the unsigned 32 bit big-endian integer at offset +<para>returns the value of the unsigned 32 bit big-endian integer at offset pos within buffer buf.</para> </sect2> <sect2> <title>RSSVAL(buf,pos,val)</title> -<para>sets the value of the unsigned short (16 bit) big-endian integer at +<para>sets the value of the unsigned short (16 bit) big-endian integer at offset pos within buffer buf to value val. refered to as "USHORT".</para> </sect2> <sect2> <title>RSIVAL(buf,pos,val)</title> -<para>sets the value of the unsigned 32 bit big-endian integer at offset +<para>sets the value of the unsigned 32 bit big-endian integer at offset pos within buffer buf to value val.</para> </sect2> @@ -249,7 +249,7 @@ reliable. <para> <programlisting> -call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, +call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, char *param, char *data, char **rparam, char **rdata); </programlisting> </para> @@ -288,7 +288,7 @@ remote api. parameters. The caller of call_api() must deallocate this memory. </para></listitem> <listitem><para> - rdata: a pointer to a pointer which will be set to point to the returned + rdata: a pointer to a pointer which will be set to point to the returned data. The caller of call_api() must deallocate this memory. </para></listitem> </orderedlist> @@ -329,7 +329,7 @@ should be the same as mdrcnt. This value should be set with SSVAL(). </para></listitem> <listitem><para> -An ASCIIZ string describing substructures which should be returned. If no +An ASCIIZ string describing substructures which should be returned. If no substructures apply, this string is of zero length. </para></listitem> @@ -352,20 +352,20 @@ are:</para> <orderedlist> <listitem><para> -An unsigned 16 bit integer which contains the API function's return code. +An unsigned 16 bit integer which contains the API function's return code. This value should be read with SVAL(). </para></listitem> <listitem><para> An adjustment which tells the amount by which pointers in the returned -data should be adjusted. This value should be read with SVAL(). Basically, +data should be adjusted. This value should be read with SVAL(). Basically, the address of the start of the returned data buffer should have the returned pointer value added to it and then have this value subtracted from it in order to obtain the currect offset into the returned data buffer. </para></listitem> <listitem><para> -A count of the number of elements in the array of structures returned. +A count of the number of elements in the array of structures returned. It is also possible that this may sometimes be the number of bytes returned. </para></listitem> </orderedlist> @@ -384,7 +384,7 @@ use. </para> <para> -The returned data buffer contains the array of returned data structures. +The returned data buffer contains the array of returned data structures. Note that all pointers must be adjusted before use. The function fix_char_ptr() in client.c can be used for this purpose. </para> diff --git a/docs-xml/Samba3-Developers-Guide/modules.xml b/docs-xml/Samba-Developers-Guide/modules.xml index f0d19f1b8e9..f452d3e3510 100644 --- a/docs-xml/Samba3-Developers-Guide/modules.xml +++ b/docs-xml/Samba-Developers-Guide/modules.xml @@ -22,7 +22,7 @@ The new modules system has the following advantages: </para> <simplelist> -<member>Transparent loading of static and shared modules (no need +<member>Transparent loading of static and shared modules (no need for a subsystem to know about modules)</member> <member>Simple selection between shared and static modules at configure time</member> <member>"preload modules" option for increasing performance for stable modules</member> @@ -35,10 +35,10 @@ for a subsystem to know about modules)</member> <title>Loading modules</title> <para> -Some subsystems in samba use different backends. These backends can be -either statically linked in to samba or available as a plugin. A subsystem -should have a function that allows a module to register itself. For example, -the passdb subsystem has: +Some subsystems in samba use different backends. These backends can be +either statically linked in to samba or available as a plugin. A subsystem +should have a function that allows a module to register itself. For example, +the passdb subsystem has: </para> <para><programlisting> @@ -46,17 +46,17 @@ NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function in </programlisting></para> <para> -This function will be called by the initialisation function of the module to -register itself. +This function will be called by the initialisation function of the module to +register itself. </para> <sect2> <title>Static modules</title> <para> -The modules system compiles a list of initialisation functions for the -static modules of each subsystem. This is a define. For example, -it is here currently (from <filename>include/config.h</filename>): +The modules system compiles a list of initialisation functions for the +static modules of each subsystem. This is a define. For example, +it is here currently (from <filename>include/config.h</filename>): </para> <para><programlisting> @@ -65,8 +65,8 @@ it is here currently (from <filename>include/config.h</filename>): </programlisting></para> <para> -These functions should be called before the subsystem is used. That -should be done when the subsystem is initialised or first used. +These functions should be called before the subsystem is used. That +should be done when the subsystem is initialised or first used. </para> </sect2> @@ -75,17 +75,17 @@ should be done when the subsystem is initialised or first used. <title>Shared modules</title> <para> -If a subsystem needs a certain backend, it should check if it has -already been registered. If the backend hasn't been registered already, +If a subsystem needs a certain backend, it should check if it has +already been registered. If the backend hasn't been registered already, the subsystem should call smb_probe_module(char *subsystem, char *backend). This function tries to load the correct module from a certain path -($LIBDIR/subsystem/backend.so). If the first character in 'backend' -is a slash, smb_probe_module() tries to load the module from the +($LIBDIR/subsystem/backend.so). If the first character in 'backend' +is a slash, smb_probe_module() tries to load the module from the absolute path specified in 'backend'. </para> -<para>After smb_probe_module() has been executed, the subsystem -should check again if the module has been registered. +<para>After smb_probe_module() has been executed, the subsystem +should check again if the module has been registered. </para> </sect2> @@ -95,7 +95,7 @@ should check again if the module has been registered. <title>Writing modules</title> <para> -Each module has an initialisation function. For modules that are +Each module has an initialisation function. For modules that are included with samba this name is '<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()). The prototype for these functions is: </para> @@ -104,8 +104,8 @@ The prototype for these functions is: NTSTATUS init_module(TALLOC_CTX *); </programlisting></para> -<para>This function should call one or more -registration functions. The function should return NT_STATUS_OK on success and +<para>This function should call one or more +registration functions. The function should return NT_STATUS_OK on success and NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</para> <para>For example, pdb_ldap_init() contains: </para> @@ -133,14 +133,14 @@ free on exist should use the NULL talloc context. <title>Static/Shared selection in configure.in</title> <para> -Some macros in configure.in generate the various defines and substs that -are necessary for the system to work correct. All modules that should -be built by default have to be added to the variable 'default_modules'. +Some macros in configure.in generate the various defines and substs that +are necessary for the system to work correct. All modules that should +be built by default have to be added to the variable 'default_modules'. For example, if ldap is found, pdb_ldap is added to this variable. </para> <para> -On the bottom of configure.in, SMB_MODULE() should be called +On the bottom of configure.in, SMB_MODULE() should be called for each module and SMB_SUBSYSTEM() for each subsystem. </para> @@ -151,23 +151,23 @@ SMB_MODULE(<replaceable>subsystem</replaceable>_<replaceable>backend</replaceabl SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>,<replaceable>depfile</replaceable>) </programlisting></para> -<para>The depfile for a certain subsystem is the file that calls the +<para>The depfile for a certain subsystem is the file that calls the initialisation functions for the statically built in modules.</para> <para> -<replaceable>@SUBSYSTEM_MODULES@</replaceable> in Makefile.in will +<replaceable>@SUBSYSTEM_MODULES@</replaceable> in Makefile.in will be replaced with the names of the plugins to build. </para> -<para>You must make sure all .c files that contain defines that can -be changed by ./configure are rebuilded in the 'modules_clean' make target. +<para>You must make sure all .c files that contain defines that can +be changed by ./configure are rebuilded in the 'modules_clean' make target. Practically, this means all c files that contain <command>static_init_subsystem;</command> calls need to be rebuilded. </para> <note> <para> There currently also is a configure.in command called SMB_MODULE_PROVIVES(). -This is used for modules that register multiple things. It should not +This is used for modules that register multiple things. It should not be used as probing will most likely disappear in the future.</para> </note> diff --git a/docs-xml/Samba3-Developers-Guide/packagers.xml b/docs-xml/Samba-Developers-Guide/packagers.xml index 853dad95e71..16248bfe906 100644 --- a/docs-xml/Samba3-Developers-Guide/packagers.xml +++ b/docs-xml/Samba-Developers-Guide/packagers.xml @@ -30,7 +30,7 @@ Version 2.999+3.0.alpha21-5 for Debian <title>Modules</title> <para> -Samba3 has support for building parts of samba as plugins. This makes it possible to, for example, +Samba has support for building parts of samba as plugins. This makes it possible to, for example, put ldap or mysql support in a separate package, thus making it possible to have a normal samba package not depending on ldap or mysql. To build as much parts of samba as a plugin, run: </para> diff --git a/docs-xml/Samba3-Developers-Guide/parsing.xml b/docs-xml/Samba-Developers-Guide/parsing.xml index d695f9313cf..0aeaad5e4c3 100644 --- a/docs-xml/Samba3-Developers-Guide/parsing.xml +++ b/docs-xml/Samba-Developers-Guide/parsing.xml @@ -75,11 +75,11 @@ The lexical analyzer scans past white space at the beginning of a line. <listitem><para> Section and parameter names may contain internal white space. All -whitespace within a name is compressed to a single space character. +whitespace within a name is compressed to a single space character. </para></listitem> <listitem><para> -Internal whitespace within a parameter value is kept verbatim with +Internal whitespace within a parameter value is kept verbatim with the exception of carriage return characters ('\r'), all of which are removed. </para></listitem> diff --git a/docs-xml/Samba3-Developers-Guide/printing.xml b/docs-xml/Samba-Developers-Guide/printing.xml index bbdbb85ef70..256ab9861a9 100644 --- a/docs-xml/Samba3-Developers-Guide/printing.xml +++ b/docs-xml/Samba-Developers-Guide/printing.xml @@ -137,11 +137,11 @@ steps ( refer to <filename>print.c:print_queue_update()</filename> ): </para> <orderedlist> - <listitem><para>Check to see if another smbd is currently in - the process of updating the queue contents by checking the pid - stored in <constant>LOCK/<replaceable>printer_name</replaceable></constant>. + <listitem><para>Check to see if another smbd is currently in + the process of updating the queue contents by checking the pid + stored in <constant>LOCK/<replaceable>printer_name</replaceable></constant>. If so, then do not update the TDB.</para></listitem> - + <listitem><para>Lock the mutex entry in the TDB and store our own pid. Check that this succeeded, else fail.</para></listitem> @@ -152,7 +152,7 @@ steps ( refer to <filename>print.c:print_queue_update()</filename> ): <listitem><para><programlisting> foreach job in the queue - { + { if the job is a UNIX job, create a new entry; if the job has a Windows based jobid, then { @@ -168,9 +168,9 @@ steps ( refer to <filename>print.c:print_queue_update()</filename> ): in the in the lpq listing</para></listitem> <listitem><para>Store the print queue status in the TDB</para></listitem> - + <listitem><para>update the cache time stamp again</para></listitem> - + </orderedlist> <para> @@ -334,7 +334,7 @@ RPC. This packet contains <itemizedlist> - + <listitem><para>the printer handle registered with the client's spooler on which the change occurred</para></listitem> diff --git a/docs-xml/Samba3-Developers-Guide/rpc_plugin.xml b/docs-xml/Samba-Developers-Guide/rpc_plugin.xml index cc263ffc3e6..1992c5703d6 100644 --- a/docs-xml/Samba3-Developers-Guide/rpc_plugin.xml +++ b/docs-xml/Samba-Developers-Guide/rpc_plugin.xml @@ -47,7 +47,7 @@ the shared library. Check the chapter on modules for more information. </para> <para> -In the init_module function, the library should call +In the init_module function, the library should call rpc_pipe_register_commands(). This function takes the following arguments: </para> @@ -59,10 +59,10 @@ NTSTATUS rpc_pipe_register_commands(int version, const char *clnt, const char *s <variablelist> <varlistentry><term>version</term> -<listitem><para>Version number of the RPC interface. Use the define <emphasis>SMB_RPC_INTERFACE_VERSION</emphasis> for this +<listitem><para>Version number of the RPC interface. Use the define <emphasis>SMB_RPC_INTERFACE_VERSION</emphasis> for this argument.</para></listitem> </varlistentry> - + <varlistentry><term>clnt</term> <listitem><para>the Client name of the named pipe</para></listitem> </varlistentry> diff --git a/docs-xml/Samba3-Developers-Guide/unix-smb.xml b/docs-xml/Samba-Developers-Guide/unix-smb.xml index 3412019fe13..53d41b7d6b8 100644 --- a/docs-xml/Samba3-Developers-Guide/unix-smb.xml +++ b/docs-xml/Samba-Developers-Guide/unix-smb.xml @@ -39,7 +39,7 @@ on the server. <para> Unix security is based around username/password pairs. A unix box should not allow clients to do any substantive operation without some -sort of validation. +sort of validation. </para> <para> @@ -145,7 +145,7 @@ details. <sect1> <title>Locking</title> <para> -Since samba 2.2, samba supports other types of locking as well. This +Since samba 2.2, samba supports other types of locking as well. This section is outdated. </para> @@ -204,7 +204,7 @@ the file for reading should fail. <para> Unix has no equivalent notion. To implement this Samba uses either lock files based on the files inode and placed in a separate lock -directory or a shared memory implementation. The lock file method +directory or a shared memory implementation. The lock file method is clumsy and consumes processing and file resources, the shared memory implementation is vastly preferred and is turned on by default for those systems that support it. @@ -306,12 +306,11 @@ this protocol level much easier. There is also a problem with the SMB specications. SMB is a X/Open spec, but the X/Open book is far from ideal, and fails to cover many important issues, leaving much to the imagination. Microsoft recently -renamed the SMB protocol CIFS (Common Internet File System) and have -published new specifications. These are far superior to the old -X/Open documents but there are still undocumented calls and features. -This specification is actively being worked on by a CIFS developers +renamed the SMB protocol CIFS (Common Internet File System) and have +published new specifications. These are far superior to the old +X/Open documents but there are still undocumented calls and features. +This specification is actively being worked on by a CIFS developers mailing list hosted by Microsft. </para> </sect1> </chapter> - diff --git a/docs-xml/Samba3-Developers-Guide/vfs.xml b/docs-xml/Samba-Developers-Guide/vfs.xml index 70e2c65c32d..99ef33ff3fb 100644 --- a/docs-xml/Samba3-Developers-Guide/vfs.xml +++ b/docs-xml/Samba-Developers-Guide/vfs.xml @@ -182,41 +182,41 @@ typedef enum _vfs_op_type { 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, + 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, + 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 (*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, + 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; }; @@ -227,7 +227,7 @@ This macros SHOULD be used to call any vfs operation. DO NOT ACCESS conn->vfs.ops.* directly !!! <programlisting> ... - + /* File operations */ #define SMB_VFS_OPEN(conn, fname, flags, mode) \ ((conn)->vfs.ops.open((conn)->vfs.handles.open,\ @@ -261,8 +261,8 @@ DO NOT ACCESS conn->vfs.ops.* directly !!! <title>Possible VFS operation layers</title> <para> -These values are used by the VFS subsystem when building the conn->vfs -and conn->vfs_opaque structs for a connection with multiple VFS modules. +These values are used by the VFS subsystem when building the conn->vfs +and conn->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> @@ -273,8 +273,8 @@ 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 +<para> +Other layer types (logger, splitter, scanner) were designed to provide different degree of transparency and for diagnosing VFS module behaviour. </para> @@ -310,7 +310,7 @@ typedef enum _vfs_op_layer { <title>Initialization and registration</title> <para> -As each Samba module a VFS module should have a +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> @@ -334,7 +334,7 @@ NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tu </varlistentry> <varlistentry><term>name</term> -<listitem><para>this is the name witch can be listed in the +<listitem><para>this is the name witch can be listed in the <command>vfs objects</command> parameter to use this module.</para></listitem> </varlistentry> @@ -348,7 +348,7 @@ this is an array of vfs_op_tuple's. </variablelist> <para> -For each operation the module wants to provide it has a entry in the +For each operation the module wants to provide it has a entry in the vfs_op_tuple array. </para> @@ -379,7 +379,7 @@ typedef struct _vfs_op_tuple { <para>A simple example:</para> <programlisting> -static vfs_op_tuple example_op_tuples[] = { +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}, @@ -582,8 +582,8 @@ e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); </para></listitem> <listitem><para> -(Only for 2.2.* modules) -Convert the old struct vfs_ops example_ops to +(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> @@ -658,11 +658,11 @@ struct vfs_ops example_ops = { }; </programlisting> -> -<programlisting> +<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}, @@ -673,7 +673,7 @@ static vfs_op_tuple example_op_tuples[] = { </para></listitem> <listitem><para> -Move the example_op_tuples[] array to the end of the file. +Move the example_op_tuples[] array to the end of the file. </para></listitem> <listitem><para> @@ -698,7 +698,7 @@ remember the struct smb_vfs_handle_struct. </para></listitem> <listitem><para> -(Only for 3.0alpha* modules) +(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> @@ -716,16 +716,16 @@ Decide if it wouldn't be better to have this data on a connection basis. </simplelist> e.g. if you have such a struct: -<programlisting> +<programlisting> struct example_privates { char *some_string; int db_connection; }; -</programlisting> +</programlisting> first way of doing it: <programlisting> static int example_connect(vfs_handle_struct *handle, - connection_struct *conn, const char *service, + connection_struct *conn, const char *service, const char* user) { struct example_privates *data = NULL; @@ -759,15 +759,15 @@ static int example_connect(vfs_handle_struct *handle, 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,("some_string: %s\n",data->some_string)); - + return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); } </programlisting> @@ -776,17 +776,17 @@ second way of doing it: static void free_example_privates(void **datap) { struct example_privates *data = (struct example_privates *)*datap; - + SAFE_FREE(data->some_string); SAFE_FREE(data); - + *datap = NULL; - + return; } -static int example_connect(vfs_handle_struct *handle, - connection_struct *conn, const char *service, +static int example_connect(vfs_handle_struct *handle, + connection_struct *conn, const char *service, const char* user) { struct example_privates *data = NULL; @@ -819,15 +819,15 @@ static int example_connect(vfs_handle_struct *handle, 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,("some_string: %s\n",data->some_string)); - + return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); } </programlisting> @@ -840,14 +840,14 @@ configure.in, (configure), install.sh and Makefile.in with the module. </para> <para> -The configure script accepts <option>--with-samba-source</option> to specify +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. +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 +The idea is that you can extend this <filename>configure.in</filename> and <filename>Makefile.in</filename> scripts for your module. </para></listitem> @@ -892,9 +892,9 @@ Overload only the functions you really need to! <title>Implement OPAQUE functions</title> <para> -If you want to just implement a better version of a +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) +(e.g. like a disk_free() function for a special filesystem) it's ok to just overload that specific function. </para> diff --git a/docs-xml/Samba3-Developers-Guide/wins.xml b/docs-xml/Samba-Developers-Guide/wins.xml index df29627bfdf..e7a6e85ff87 100644 --- a/docs-xml/Samba3-Developers-Guide/wins.xml +++ b/docs-xml/Samba-Developers-Guide/wins.xml @@ -18,7 +18,7 @@ <para> The current Samba codebase possesses the capability to use groups of WINS -servers that share a common namespace for NetBIOS name registration and +servers that share a common namespace for NetBIOS name registration and resolution. The formal parameter syntax is </para> @@ -60,20 +60,20 @@ interface names in the tags is only by convention and is not a technical require </programlisting></para> <para> -Using this configuration, nmbd would attempt to register the server's NetBIOS name -with one WINS server in each group. Because the "eth0" group has two servers, the -second server would only be used when a registration (or resolution) request to +Using this configuration, nmbd would attempt to register the server's NetBIOS name +with one WINS server in each group. Because the "eth0" group has two servers, the +second server would only be used when a registration (or resolution) request to the first server in that group timed out. </para> <para> -NetBIOS name resolution follows a similar pattern as name registration. When resolving -a NetBIOS name via WINS, smbd and other Samba programs will attempt to query a single WINS -server in a tagged group until either a positive response is obtained at least once or +NetBIOS name resolution follows a similar pattern as name registration. When resolving +a NetBIOS name via WINS, smbd and other Samba programs will attempt to query a single WINS +server in a tagged group until either a positive response is obtained at least once or until a server from every tagged group has responded negatively to the name query request. -If a timeout occurs when querying a specific WINS server, that server is marked as down to -prevent further timeouts and the next server in the WINS group is contacted. Once marked as -dead, Samba will not attempt to contact that server for name registration/resolution queries +If a timeout occurs when querying a specific WINS server, that server is marked as down to +prevent further timeouts and the next server in the WINS group is contacted. Once marked as +dead, Samba will not attempt to contact that server for name registration/resolution queries for a period of 10 minutes. </para> diff --git a/docs-xml/htmldocs.html b/docs-xml/htmldocs.html index 6fb9e73a6a1..cf646de436b 100644 --- a/docs-xml/htmldocs.html +++ b/docs-xml/htmldocs.html @@ -11,7 +11,7 @@ </div> <hr> <table> - <td valign="top">SAMBA <a href="Samba3-Developers-Guide/index.html">Developers</a> Guide</td> + <td valign="top">SAMBA <a href="Samba-Developers-Guide/index.html">Developers</a> Guide</td> <td valign="top">This book is a collection of documents that might be useful for people developing samba or those interested in doing so. It's nothing more than a collection of documents written by samba developers about the internals of various parts of samba and the SMB protocol. It's still (and will always be) incomplete.</td> </tr> <tr> |