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>
<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>
<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>
</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>
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>
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>
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
<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>
</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>
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>
<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>
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>
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>
</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.
<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>
<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>
<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>
<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,
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
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>
<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>
<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
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>
<?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">
]>
<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>
</bookinfo>
-<xi:include href="../Samba3-Developers-Guide-attributions.xml">
+<xi:include href="../Samba-Developers-Guide-attributions.xml">
<xi:fallback/>
</xi:include>
<part>
<title>Samba Subsystems</title>
-
+
<xi:include href="rpc_plugin.xml"/>
<xi:include href="vfs.xml"/>
<xi:include href="parsing.xml"/>
<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>
character set that is used does need the following properties:
</para>
<orderedlist>
-
+
<listitem><para>
must not contain NULLs except for termination
</para></listitem>
<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
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
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>
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
<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>
<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>
<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>
<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>
<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>
<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>
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>
</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>
<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>
</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>
</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>
<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>
</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>
</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>
<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>
<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>
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>
<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>
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>
<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>
<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>
</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>
<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
{
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>
<itemizedlist>
-
+
<listitem><para>the printer handle registered with the
client's spooler on which the change occurred</para></listitem>
</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>
<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>
<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>
<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>
<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.
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>
-
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;
};
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,\
<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>
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>
<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>
</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>
</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>
<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},
</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>
};
</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},
</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>
</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>
</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;
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>
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;
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>
</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>
<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>
<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>
</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>
</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>
git.samba.org / garming / samba-autobuild / .git / commitdiff