README
1This is the release version of Samba, the free SMB and CIFS client and
2server for UNIX and other operating systems. Samba is maintained by
3the Samba Team, who support the original author, Andrew Tridgell.
4
5>>>> Please read THE WHOLE of this file as it gives important information
6>>>> about the configuration and use of Samba.
7
8NOTE: Installation instructions may be found in
9 docs/htmldocs/Samba3-HOWTO/install.html
10
11This software is freely distributable under the GNU public license, a
12copy of which you should have received with this software (in a file
13called COPYING).
14
15
16WHAT IS SMB/CIFS?
17=================
18
19This is a big question.
20
21The very short answer is that it is the protocol by which a lot of
22PC-related machines share files and printers and other information
23such as lists of available files and printers. Operating systems that
24support this natively include Windows 9x, Windows NT (and derivatives),
25OS/2, Mac OS X and Linux. Add on packages that achieve the same
26thing are available for DOS, Windows 3.1, VMS, Unix of all kinds,
27MVS, and more. Some Web Browsers can speak this protocol as well
28(smb://). Alternatives to SMB include Netware, NFS, Appletalk,
29Banyan Vines, Decnet etc; many of these have advantages but none are
30both public specifications and widely implemented in desktop machines
31by default.
32
33The Common Internet File system (CIFS) is what the new SMB initiative
34is called. For details watch http://samba.org/cifs.
35
36
37WHY DO PEOPLE WANT TO USE SMB?
38==============================
39
401. Many people want to integrate their Microsoft desktop clients
41 with their Unix servers.
42
432. Others want to integrate their Microsoft (etc) servers with Unix
44 servers. This is a different problem to integrating desktop
45 clients.
46
473. Others want to replace protocols like NFS, DecNet and Novell NCP,
48 especially when used with PCs.
49
50
51WHAT CAN SAMBA DO?
52==================
53
54Please refer to the WHATSNEW.txt included with this README for
55a list of features in the latest Samba release.
56
57Here is a very short list of what samba includes, and what it does.
58For many networks this can be simply summarized by "Samba provides
59a complete replacement for Windows NT, Warp, NFS or Netware servers."
60
61- a SMB server, to provide Windows NT and LAN Manager-style file and print
62 services to SMB clients such as Windows 95, Warp Server, smbfs and others.
63
64- a Windows NT 4.0 Domain Controller replacement.
65
66- a file/print server that can act as a member of a Windows NT 4.0
67 or Active Directory domain.
68
69- a NetBIOS (rfc1001/1002) nameserver, which amongst other things gives
70 browsing support. Samba can be the master browser on your LAN if you wish.
71
72- a ftp-like SMB client so you can access PC resources (disks and
73 printers) from UNIX, Netware, and other operating systems
74
75- a tar extension to the client for backing up PCs
76
77- limited command-line tool that supports some of the NT administrative
78 functionality, which can be used on Samba, NT workstation and NT server.
79
80For a much better overview have a look at the web site at
81http://samba.org/samba, and browse the user survey.
82
83Related packages include:
84
85- smbfs, a Linux-only filesystem allowing you to mount remote SMB
86 filesystems from PCs on your Linux box. This is included as standard with
87 Linux 2.0 and later.
88
89- cifsvfs, a more advanced Linux-only filesystem allowing you to mount
90 remote SMB filesystems from PCs on your Linux box. This is included
91 as standard with Linux 2.5 and later.
92
93
94
95CONTRIBUTIONS
96=============
97
98If you want to contribute to the development of the software then
99please join the mailing list. The Samba team accepts patches
100(preferably in "diff -u" format, see http://samba.org/samba/devel/
101for more details) and are always glad to receive feedback or
102suggestions to the address samba@lists.samba.org. More information
103on the various Samba mailing lists can be found at http://lists.samba.org/.
104
105You can also get the Samba sourcecode straight from the git repository - see
106http://wiki.samba.org/index.php/Using_Git_for_Samba_Development.
107
108You could also send hardware/software/money/jewelry or pre-paid pizza
109vouchers directly to Andrew. The pizza vouchers would be especially
110welcome, in fact there is a special field in the survey for people who
111have paid up their pizza :-)
112
113If you like a particular feature then look through the git change-log
114(on the web at http://gitweb.samba.org/?p=samba.git;a=summary) and see
115who added it, then send them an email.
116
117Remember that free software of this kind lives or dies by the response
118we get. If no one tells us they like it then we'll probably move onto
119something else. However, as you can see from the user survey quite a lot of
120people do seem to like it at the moment :-)
121
122
123MORE INFO
124=========
125
126DOCUMENTATION
127-------------
128
129There is quite a bit of documentation included with the package,
130including man pages, and lots of .html files with hints and useful
131info. This is also available from the web page. There is a growing
132collection of information under docs/.
133
134A list of Samba documentation in languages other than English is
135available on the web page.
136
137If you would like to help with the documentation, please coodinate
138on the samba@samba.org mailing list. See the next section for details
139on subscribing to samba mailing lists.
140
141
142MAILING LIST
143------------
144
145Please do NOT send subscription/unsubscription requests to the lists!
146
147There is a mailing list for discussion of Samba. For details go to
148<http://lists.samba.org/> or send mail to <samba-subscribe@lists.samba.org>
149
150There is also an announcement mailing list where new versions are
151announced. To subscribe go to <http://lists.samba.org/> or send mail
152to <samba-announce-subscribe@lists.samba.org>. All announcements also
153go to the samba list, so you only need to be on one.
154
155For details of other Samba mailing lists and for access to archives, see
156<http://lists.samba.org/>
157
158
159MAILING LIST ETIQUETTE
160----------------------
161
162A few tips when submitting to this or any mailing list.
163
1641. Make your subject short and descriptive. Avoid the words "help" or
165 "Samba" in the subject. The readers of this list already know that
166 a) you need help, and b) you are writing about samba (of course,
167 you may need to distinguish between Samba PDC and other file
168 sharing software). Avoid phrases such as "what is" and "how do
169 i". Some good subject lines might look like "Slow response with
170 Excel files" or "Migrating from Samba PDC to NT PDC".
171
1722. If you include the original message in your reply, trim it so that
173 only the relevant lines, enough to establish context, are
174 included. Chances are (since this is a mailing list) we've already
175 read the original message.
176
1773. Trim irrelevant headers from the original message in your
178 reply. All we need to see is a) From, b) Date, and c) Subject. We
179 don't even really need the Subject, if you haven't changed
180 it. Better yet is to just preface the original message with "On
181 [date] [someone] wrote:".
182
1834. Please don't reply to or argue about spam, spam filters or viruses
184 on any Samba lists. We do have a spam filtering system that is
185 working quite well thank you very much but occasionally unwanted
186 messages slip through. Deal with it.
187
1885. Never say "Me too." It doesn't help anyone solve the
189 problem. Instead, if you ARE having the same problem, give more
190 information. Have you seen something that the other writer hasn't
191 mentioned, which may be helpful?
192
1936. If you ask about a problem, then come up with the solution on your
194 own or through another source, by all means post it. Someone else
195 may have the same problem and is waiting for an answer, but never
196 hears of it.
197
1987. Give as much *relevant* information as possible such as Samba
199 release number, OS, kernel version, etc...
200
2018. RTFM. Google. groups.google.com.
202
203
204NEWS GROUP
205----------
206
207You might also like to look at the usenet news group comp.protocols.smb
208as it often contains lots of useful info and is frequented by lots of
209Samba users. The newsgroup was initially setup by people on the Samba
210mailing list. It is not, however, exclusive to Samba, it is a forum for
211discussing the SMB protocol (which Samba implements). The samba list
212is gatewayed to this newsgroup.
213
214
215WEB SITE
216--------
217
218A Samba WWW site has been setup with lots of useful info. Connect to:
219
220http://samba.org/samba/
221
222As well as general information and documentation, this also has searchable
223archives of the mailing list and a user survey that shows who else is using
224this package. Have you registered with the survey yet? :-)
225
226
README.Coding
1Coding conventions in the Samba tree
2~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3
4.. contents::
5
6===========
7Quick Start
8===========
9
10Coding style guidelines are about reducing the number of unnecessary
11reformatting patches and making things easier for developers to work together.
12You don't have to like them or even agree with them, but once put in place
13we all have to abide by them (or vote to change them). However, coding
14style should never outweigh coding itself and so the guidelines
15described here are hopefully easy enough to follow as they are very
16common and supported by tools and editors.
17
18The basic style, also mentioned in prog_guide4.txt, is the Linux kernel coding
19style (See Documentation/CodingStyle in the kernel source tree). This closely
20matches what most Samba developers use already anyways.
21
22But to save you the trouble of reading the Linux kernel style guide, here
23are the highlights.
24
25* Maximum Line Width is 80 Characters
26 The reason is not for people with low-res screens but rather sticking
27 to 80 columns prevents you from easily nesting more than one level of
28 if statements or other code blocks. Use source3/script/count_80_col.pl
29 to check your changes.
30
31* Use 8 Space Tabs to Indent
32 No whitespace filler.
33
34* No Trailing Whitespace
35 Use source3/script/strip_trail_ws.pl to clean you files before committing.
36
37* Follow the K&R guidelines. We won't go throw them all here. You have
38 a copy of "The C Programming Language" anyways right? You can also use
39 the format_indent.sh script found in source3/script/ if all else fails.
40
41
42
43============
44Editor Hints
45============
46
47Emacs
48-----
49Add the follow to your $HOME/.emacs file:
50
51 (add-hook 'c-mode-hook
52 (lambda ()
53 (c-set-style "linux")
54 (c-toggle-auto-state)))
55
56
57Vi
58--
59(Thanks to SATOH Fumiyasu <fumiyas@osstech.jp> for these hints):
60
61For the basic vi editor included with all variants of \*nix, add the
62following to $HOME/.exrc:
63
64 set tabstop=8
65 set shiftwidth=8
66
67For Vim, the following settings in $HOME/.vimrc will also deal with
68displaying trailing whitespace::
69
70 if has("syntax") && (&t_Co > 2 || has("gui_running"))
71 syntax on
72 function! ActivateInvisibleCharIndicator()
73 syntax match TrailingSpace "[ \t]\+$" display containedin=ALL
74 highlight TrailingSpace ctermbg=Red
75 endf
76 autocmd BufNewFile,BufRead * call ActivateInvisibleCharIndicator()
77 endif
78 " Show tabs, trailing whitespace, and continued lines visually
79 set list listchars=tab:����,trail:��,extends:���
80
81 " highlight overly long lines same as TODOs.
82 set textwidth=80
83 autocmd BufNewFile,BufRead *.c,*.h exec 'match Todo /\%>' . &textwidth . 'v.\+/'
84
85
86=========================
87FAQ & Statement Reference
88=========================
89
90Comments
91--------
92
93Comments should always use the standard C syntax. C++
94style comments are not currently allowed.
95
96
97Indention & Whitespace & 80 columns
98-----------------------------------
99
100To avoid confusion, indentations are to be 8 character with tab (not
1018 ' ' characters. When wrapping parameters for function calls,
102align the parameter list with the first parameter on the previous line.
103Use tabs to get as close as possible and then fill in the final 7
104characters or less with whitespace. For example,
105
106 var1 = foo(arg1, arg2,
107 arg3);
108
109The previous example is intended to illustrate alignment of function
110parameters across lines and not as encourage for gratuitous line
111splitting. Never split a line before columns 70 - 79 unless you
112have a really good reason. Be smart about formatting.
113
114
115If, switch, & Code blocks
116-------------------------
117
118Always follow an 'if' keyword with a space but don't include additional
119spaces following or preceding the parentheses in the conditional.
120This is good:
121
122 if (x == 1)
123
124This is bad:
125
126 if ( x == 1 )
127
128Yes we have a lot of code that uses the second form and we are trying
129to clean it up without being overly intrusive.
130
131Note that this is a rule about parentheses following keywords and not
132functions. Don't insert a space between the name and left parentheses when
133invoking functions.
134
135Braces for code blocks used by for, if, switch, while, do..while, etc.
136should begin on the same line as the statement keyword and end on a line
137of their own. NOTE: Functions are different and the beginning left brace
138should begin on a line of its own.
139
140If the beginning statement has to be broken across lines due to length,
141the beginning brace should be on a line of its own.
142
143The exception to the ending rule is when the closing brace is followed by
144another language keyword such as else or the closing while in a do..while
145loop.
146
147Good examples::
148
149 if (x == 1) {
150 printf("good\n");
151 }
152
153 for (x=1;
154 x<10;
155 x++)
156 {
157 print("%d\n", x);
158 }
159
160 do {
161 printf("also good\n");
162 } while (1);
163
164Bad examples::
165
166 while (1)
167 {
168 print("I'm in a loop!\n"); }
169
170
171Goto
172----
173
174While many people have been academically taught that goto's are fundamentally
175evil, they can greatly enhance readability and reduce memory leaks when used
176as the single exit point from a function. But in no Samba world what so ever
177is a goto outside of a function or block of code a good idea.
178
179Good Examples::
180
181 int function foo(int y)
182 {
183 int *z = NULL;
184 int ret = 0;
185
186 if ( y < 10 ) {
187 z = malloc(sizeof(int)*y);
188 if (!z) {
189 ret = 1;
190 goto done;
191 }
192 }
193
194 print("Allocated %d elements.\n", y);
195
196 done:
197 if (z)
198 free(z);
199
200 return ret;
201 }
202
203
204Checking Pointer Values
205-----------------------
206
207When invoking functions that return pointer values, either of the following
208are acceptable. Use you best judgement and choose the more readable option.
209Remember that many other people will review it.::
210
211 if ((x = malloc(sizeof(short)*10)) == NULL ) {
212 fprintf(stderr, "Unable to alloc memory!\n");
213 }
214
215or::
216
217 x = malloc(sizeof(short)*10);
218 if (!x) {
219 fprintf(stderr, "Unable to alloc memory!\n");
220 }
221
222
223Primitive Data Types
224--------------------
225
226Samba has large amounts of historical code which makes use of data types
227commonly supported by the C99 standard. However, at the time such types
228as boolean and exact width integers did not exist and Samba developers
229were forced to provide their own. Now that these types are guaranteed to
230be available either as part of the compiler C99 support or from lib/replace/,
231new code should adhere to the following conventions:
232
233 * Booleans are of type "bool" (not BOOL)
234 * Boolean values are "true" and "false" (not True or False)
235 * Exact width integers are of type [u]int[8|16|32|64]_t
236