workbench/network/smbfs/documentation/smbfs.html

   1 <!DOCTYPE html public "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <head>
   4 <title>A SMB file system wrapper for AmigaOS, using the AmiTCP V3 API</title>
   5 <body>
   6
   7 <h1>A SMB file system wrapper for AmigaOS, using the AmiTCP V3 API</h1>
   8
   9 <h2>1. What is it?</h2>
  10
  11 <p>This document briefly describes the <b>smbfs</b> program, which implements an SMB
  12 file system for AmigaOS. This file system can be used to access files made
  13 available by file servers which implement the SMB protocol, such as <i>Microsoft
  14 Windows</i> or any other platform which supports the free <i>Samba</i> product. These
  15 files can be accessed using shell commands such as <tt>List</tt>, the <i>Workbench</i> or
  16 utilities such as <i>Directory Opus</i> as if the file server were a local disk
  17 drive.</p>
  18
  19
  20 <h2>2. What do you need to get started?</h2>
  21
  22 <p>You need a TCP/IP stack that supports the AmiTCP V3 API, such as <i>Miami</i>, the
  23 original free <i>AmiTCP 3.0</i> release, <i>AmiTCP 4.x</i>, <i>Miami Deluxe</i>, <i>AmiTCP
  24 Genesis</i> or <i>Roadshow</i> and the obligatory networking gear. All these items need to be in
  25 good shape and properly configured.</p>
  26
  27 <p>Most important, you need a computer which exports file sharing services using
  28 the SMB protocol.</p>
  29
  30 <p>It often helps to have <i>Samba</i> installed on your Amiga, too, as this can aid
  31 in tracking down bugs and obtaining information which <b>smbfs</b> cannot obtain all
  32 by itself.</p>
  33
  34 <p>Last but not least, you need to be proficient in configuring and using the
  35 TCP/IP stack; networking knowledge is definitely assumed.</p>
  36
  37 <p><b>smbfs</b> requires <i>AmigaOS 2.04</i> or higher to work.</p>
  38
  39
  40 <h2>3. Preparations</h2>
  41
  42 <p>You need to know which computer's files you want to share using the <b>smbfs</b> file
  43 system. That computer must be known by name, it is not sufficient just to know
  44 its IP address. If you know the IP address but cannot refer to the host by its
  45 name then <b>smbfs</b> will not work. In that case, make sure that you add a host
  46 name entry referring to the IP address to your TCP/IP stack's host database
  47 (e.g. the <samp>AmiTCP:bin/hosts</samp> file or the corresponding page in the stack's
  48 configuration user interface).</p>
  49
  50 <p>The name of the computer to connect to must not be too long. If it is longer
  51 than 16 characters, <b>smbfs</b> will not work properly.</p>
  52
  53 <p>You need to know which service you want to connect to on the target computer.
  54 You can find out which services are available on a certain computer by using
  55 the Samba <tt>smbclient</tt> program. For example, if you were to query the services
  56 offered by a machine called <i>sourcery</i> you could enter the following:</p>
  57
  58 <p><tt> samba:bin/smbclient -L sourcery </tt></p>
  59
  60 <p>And you might get the following information:</p>
  61
  62 <pre>
  63 added interface ip=192.168.0.1 bcast=192.168.0.255 nmask=255.255.255.0
  64 Password: Domain=[ARBEITSGRUPPE] OS=[AmigaOS] Server=[Samba 2.0.7]
  65
  66         Sharename      Type      Comment
  67         ---------      ----      -------
  68         All            Disk      All volumes in the system
  69         IPC$           IPC       IPC Service (Amiga 3000UX)
  70         olsen          Disk      Home Directories
  71
  72         Server               Comment
  73         ---------            -------
  74         SOURCERY             Amiga 3000UX
  75
  76         Workgroup            Master
  77         ---------            -------
  78         ARBEITSGRUPPE        SOURCERY
  79 </pre>
  80
  81 <p>The share name to connect to would be <tt>ALL</tt> in this case.</p>
  82
  83 <p>You need to know which login name and which password are required to connect
  84 to the shared resource, and you need to know the name of the workgroup or
  85 domain the file server is a member of.</p>
  86
  87
  88 <h2>4. Starting and stopping the file system</h2>
  89
  90 <p><b>smbfs</b> is an uncommon kind of file system in that you do not use the <tt>Mount</tt>
  91 command to mount it. In fact, <b>smbfs</b> is a shell program which can be launched
  92 from the shell, using command line parameters to tell it which resources
  93 should be used. But you can also start it from Workbench: in this case you
  94 would have to put the program's command line options into icon tool types.</p>
  95
  96 <p>By now you should have assembled the following information:</p>
  97
  98 <ul>
  99 <li> Name of the computer to connect to; this would be the file server
 100 <li> Name of the shared SMB resource to connect to
 101 <li> Login name and password
 102 </ul>
 103
 104 <p>That's basically everything you need to know to continue -- unless something
 105 goes wrong, but more on that lateron.</p>
 106
 107 <p>Now you can start the file system. For example, to connect to the file server
 108 called <i>sourcery</i> and the shared <i>all</i> resource it exports, with that computer
 109 being a member of the workgroup <i>Arbeitsgruppe</i>, using the login name
 110 <i>PCGuest</i> and not providing any password you would enter the following:</p>
 111
 112 <p><tt>Run &gt;NIL: SMBFS Workgroup=Arbeitsgruppe User=PCGuest Service=//sourcery/all</tt></p>
 113
 114 <p>This would cause a new device by the name of <tt>SMBFS:</tt> to be mounted, showing
 115 all files and directories the <i>sourcery</i> server makes available for sharing.</p>
 116
 117 <p>How do you 'unmount' the file system? That's very easy, just check the output
 118 of the <tt>Status</tt> shell command. You might get the following output:</p>
 119
 120 <p><tt>
 121 Process  1: Loaded as command: TURBOTEXT<br>
 122 Process  2: Loaded as command: Work:Tools/Blowup<br>
 123 Process  3: Loaded as command: Work:Tools/Sashimi<br>
 124 Process  4: Loaded as command: Work:CyberTools/CyberGuard<br>
 125 Process  5: Loaded as command: Work:Tools/OpenDevicePatch<br>
 126 Process  6: Loaded as command: CED<br>
 127 Process  7: Loaded as command: Workbench<br>
 128 Process  8: Loaded as command: Status<br>
 129 Process  9: No command loaded<br>
 130 Process 10: Loaded as command: SMBFS '//sourcery/all'
 131 </tt></p>
 132
 133 <p>Look at the last line describing process number 10: it shows the name of the
 134 file system program <b>smbfs</b> and the name of the SMB share it is connected to. To
 135 stop this file system and effectively unmount it, use the shell <tt>Break</tt>
 136 command; in this case you would enter <kbd>Break 10</kbd> to stop the file system. Note
 137 that the program may not terminate immediately; it may have to wait until the
 138 last client has released all resources referring to the file system. You may
 139 have to send more than one <tt>Break</tt> command to stop the program.</p>
 140
 141
 142 <h2>5. Startup options</h2>
 143
 144 <p>The <b>smbfs</b> program supports a number of command line options, as will be
 145 described below. The command template looks like this:</p>
 146
 147 <p><tt>
 148 DOMAIN=WORKGROUP/K,USER=USERNAME/K,PASSWORD/K,CHANGECASE/S,<br>
 149 CASE=CASESENSITIVE/S,OMITHIDDEN/S,QUIET/S,CLIENT=CLIENTNAME/K,<br>
 150 SERVER=SERVERNAME/K,DEVICE=DEVICENAME/K,VOLUME=VOLUMENAME/K,<br>
 151 CACHE=CACHESIZE/N/K,DEBUGLEVEL=DEBUG/N/K,TZ=TIMEZONEOFFSET/N/K,<br>
 152 DST=DSTOFFSET/N/K,TRANSLATE=TRANSLATIONFILE/K,SERVICE/A</tt></p>
 153
 154 <p>The individual options serve the following purposes:</p>
 155
 156 <ul>
 157 <li> <p><tt>DOMAIN=WORKGROUP/K</tt></p>
 158
 159 <p>You must specify the name of the work group or domain which the file server
 160 to connect to is a member of. The name of this workgroup or domain must not
 161 be longer than 16 characters. The name you provide will be translated to
 162 all upper case characters.</p>
 163
 164 <p>You need not provide for a work group or domain name on the command line.
 165 Alternatively, you may configure an environment variable whose contents
 166 will be used instead. The variable could be set up like this:</p>
 167
 168 <p><tt>
 169 SetEnv smbfs_workgroup <i>name of domain or workgroup</i><br>
 170 Copy ENV:smbfs_workgroup ENVARC:
 171 </tt></p>
 172
 173 <p>You may also use the <tt>smbfs_domain</tt> environment varilable in place of the
 174 <tt>smbfs_workgroup</tt> variable. The two are aliases for one another, but
 175 <b>smbfs</b> will read only one of the two.</p>
 176
 177 <li><p><tt>USER=USERNAME/K</tt></p>
 178
 179 <p>To connect to an SMB share you must authenticate yourself by providing a
 180 user name. With this program the user name is optional; if you do not
 181 provide one, <b>smbfs</b> will use the default, which is <tt>GUEST</tt>. The user name
 182 must not be longer than 64 characters. The name you provide will be
 183 translated to all upper case characters.</p>
 184
 185 <p>You need not provide for a user name on the command line. Alternatively,
 186 you may configure an environment variable whose contents will be used
 187 instead. The variable could be set up like this:</p>
 188
 189 <p><tt>
 190 SetEnv smbfs_username <i>your user name</i><br>
 191 Copy ENV:smbfs_username ENVARC:
 192 </tt></p>
 193
 194 <p>You may also use the <tt>smbfs_user</tt> environment varilable in place of the
 195 <tt>smbfs_username</tt> variable. The two are aliases for one another, but
 196 <b>smbfs</b> will read only one of the two.</p>
 197
 198 <li><p><tt>PASSWORD/K</tt></p>
 199
 200 <p>As part of the authentication process required to make the connection to
 201 an SMB share, you must provide for a user name and a password. The
 202 password is optional; if you do not provide one, an empty password will
 203 be transmitted. The password must not be longer than 64 characters.</p>
 204
 205 <p>You need not provide for a password on the command line. Alternatively,
 206 you may configure an environment variable whose contents will be used
 207 instead. The variable could be set up like this:</p>
 208
 209 <p><tt>
 210 SetEnv smbfs_password <i>your password</i><br>
 211 Copy ENV:smbfs_password ENVARC:</tt></p>
 212
 213 <p>Keep in mind that passwords like these really should not be exposed by
 214 storing them in environment variables. But then the protocol <b>smbfs</b> uses
 215 is almost as insecure as it gets anyway.</p>
 216
 217 <p>The authentication process only works if the machine you are connecting
 218 to knows about the user name and password you want to use. As of this
 219 writing, <b>smbfs</b> cannot be used for authenticating against a password
 220 server that is not the same machine as the one from which you wish to
 221 import a share.</p>
 222
 223 <li><p><tt>CHANGECASE/S</tt></p>
 224
 225 <p>By default the password will not be changed to all upper case characters.
 226 If this is required, you should either provide the password in this
 227 form or resort to this option, which will cause it to be translated
 228 to all upper case characters.</p>
 229
 230 <li><p><tt>CASE=CASESENSITIVE/S</tt></p>
 231
 232 <p>Some file servers treat file and directory names differently which
 233 differ only in whether they are written using upper/lower case
 234 characters. For these servers you should activate the <tt>CASESENSITIVE</tt>
 235 switch to treat those files properly. There is a catch though: the
 236 AmigaDOS file naming scheme does not follow this model and you may
 237 run into problems when you are trying to use it. By default, the
 238 file system does not treat file and directory names differently
 239 which only differ with respect to the case of letters.</p>
 240
 241 <li><p><tt>OMITHIDDEN/S</tt></p>
 242
 243 <p>When requesting a directory listing, the server may return some files
 244 and directories tagged as being hidden. By default this file system
 245 will report these 'hidden' entries anyway, but you can request
 246 specifically that what is intended to be hidden should be omitted
 247 from directory listings, too. Note that even though a file may be
 248 hidden you should still be able to open and examine it.</p>
 249
 250 <li><p><tt>QUIET/S</tt></p>
 251
 252 <p>When started from Shell, <b>smbfs</b> will print a message as soon as the
 253 connection to the file server has been established. If you do not
 254 want to see that message displayed, use the <tt>QUIET</tt> parameter. Also,
 255 no such message will appear if the program has been started to run
 256 in the background.</p>
 257
 258 <li><p><tt>CLIENT=CLIENTNAME/K</tt><p>
 259
 260 <p><b>smbfs</b> will attempt to connect to the file server by providing the name
 261 of the computer you connect from. In some cases this may be undesirable
 262 as the computer's name differs from what the file server expects. You
 263 can use the <tt>CLIENT</tt> parameter to tell <b>smbfs</b> under which name it should
 264 announce itself to the server. This parameter is optional and will be
 265 translated to all upper case characters; it cannot be longer than 16
 266 characters.</p>
 267
 268 <li><p><tt>SERVER=SERVERNAME/K</tt></p>
 269
 270 <p><b>smbfs</b> will attempt to connect to the file server by providing the name
 271 you specified using the <tt>SERVICE</tt> command line parameter. In some cases
 272 this may be undesirable as the server's name differs from what you
 273 specified as the share name. You can use the <tt>SERVER</tt> parameter to tell
 274 <b>smbfs</b> under which name it should contact the server. This parameter is
 275 optional and will be translated to all upper case characters; it cannot
 276 be longer than 16 characters.</p>
 277
 278 <li><p><tt>DEVICE=DEVICENAME/K</tt><br>
 279 <tt>VOLUME=VOLUMENAME/K</tt></p>
 280
 281 <p>The <b>smbfs</b> program can announce itself as an AmigaDOS file system by
 282 using one of two different methods.</p>
 283
 284 <p>The first method involves announcing itself only as a file system
 285 device. This should be sufficient in most cases but has a drawback in
 286 that the device will not be usable from Workbench since the file system
 287 will not appear as a disk icon. You tell <b>smbfs</b> to use a specific device
 288 name by using the <tt>DEVICE</tt> command line parameter, e.g. <kbd>DEVICE=SMBFS:</kbd>.
 289 Note that device names must be unique, i.e. there must be no other
 290 device by the same name in the system; <b>smbfs</b> will report an error and
 291 exit if it finds one.</p>
 292
 293 <p>The second method involves announcing itself as a volume. This has the
 294 benefit of making the file system usable from Workbench since a disk
 295 icon will appear for it. You tell <b>smbfs</b> to use a specific volume name by
 296 using the <tt>VOLUME</tt> command line parameter, e.g. <kbd>VOLUME=Sourcery:</kbd>.</p>
 297
 298 <p>Both methods have advantages and drawbacks. The drawback of the <tt>VOLUME</tt>
 299 method is that it may deadlock the native Amiga Samba port as soon as
 300 the file system is mounted. The drawback of the <tt>DEVICE</tt> method is that
 301 the file system will not be usable from Workbench.</p>
 302
 303 <p>If you wish, you can combine both methods; this is the approach most
 304 other file systems use. And in fact, when you tell <b>smbfs</b> to add a
 305 volume it will also add a device to go along with it.</p>
 306
 307 <p>The <tt>VOLUME</tt> and <tt>DEVICE</tt> keywords are optional; if you omit both, <b>smbfs</b>
 308 will pretend that you had used the <kbd>DEVICE=SMBFS:</kbd> parameter.</p>
 309
 310 <li><p><tt>CACHE=CACHESIZE/N/K</tt></p>
 311
 312 <p>The file system attempts to optimize accesses to the file server when
 313 directory contents are being scanned. These contents are buffered in
 314 a directory cache which by default will hold 170 entries. Since each
 315 entry will require about 255 bytes of storage, the entire 170 entry
 316 cache will occupy more than 40K bytes of memory. You may want to change
 317 this requirement, by making the cache smaller or larger using the
 318 <tt>CACHESIZE</tt> parameter. The size of the directory cache cannot be smaller
 319 than 10 entries.</p>
 320
 321 <li><p><tt>DEBUGLEVEL=DEBUG/N/K</tt></p>
 322
 323 <p>By default <b>smbfs</b> operates in silent mode. It does not report what it is
 324 doing, it just tries to respond to file system requests. To obtain
 325 debugging output you may want to use the <tt>DEBUG</tt> option and specify a
 326 debug level greater than 0. The larger the number you specify the more
 327 debugging output will be created. Note that all debugging output will be
 328 produced using the operating system's debug output functionality which
 329 requires that you have a capturing program like <tt>Sashimi</tt> running in the
 330 background.</p>
 331
 332 <li><p><tt>TZ=TIMEZONEOFFSET/N/K</tt></p>
 333
 334 <p>By default the file system will use the current Locale settings to
 335 translate between the local time and the time used by the SMB
 336 server. For some configurations, however, this is impractical since
 337 the server's time zone is not configured properly. For these
 338 rare cases you may want to hard code a certain time zone offset
 339 using the <tt>TIMEZONEOFFSET</tt> options. The number you provide must
 340 be the number of minutes to add to the local time in order to
 341 translate it into the corresponding UTC value. For example, in
 342 central Europe using CET, you would use <kbd>TZ=-60</kbd> since CET is
 343 one hour ahead of UTC.</p>
 344
 345 <li><p><tt>DST=DSTOFFSET/N/K</tt></p>
 346
 347 <p>This option can be used to adjust the file date stamps to take
 348 local daylight savings time into account. The number to specify here
 349 is by how many minutes local time has been moved ahead, which is
 350 typically 60. Note that <b>smbfs</b> does not know when daylight
 351 savings time begins and ends. It is up to you to select the correct
 352 adjustment value when appropriate.</p>
 353
 354 <li><p><tt>TRANSLATE=TRANSLATIONFILE/K</tt></p>
 355
 356 <p>The Amiga and the file server <b>smbfs</b> connects to may not share the same
 357 character set. International characters used in file names on either
 358 side may not come out correctly on the other side. To remedy this
 359 problem, you can resort to file name translation. How the individual
 360 names are to be translated is determined by the contents of a file
 361 name translation table file such as the ones that ship with Workbench
 362 in the <samp>L:FileSystem_Trans</samp> drawer. The first 256 bytes of each such
 363 file must consist of the mapping of Amiga characters to the different
 364 character set, and the second 256 characters must describe a mapping
 365 back from the different character set to the Amiga. In most cases the
 366 <samp>L:FileSystem_Trans/INTL.crossdos</samp> translation table file should be
 367 sufficient. To specify which file contains the translation tables to
 368 use you would use the <tt>TRANSLATIONFILE</tt> parameter.</p>
 369
 370 <li><p><tt>SERVICE/A</tt></p>
 371
 372 <p>This is the last parameter to be specified on the command line. It
 373 should refer to the file server you want to connect to and the resource
 374 it exports, e.g. a file system. This parameter must start with two
 375 slashes which must be immediately followed by the file server's name,
 376 which must be followed by the resource to connect to.</p>
 377
 378 <p>For now no special characters are allowed in the name of the service
 379 as no translation is performed like would be the case for file names
 380 on the volume.</p>
 381
 382 <p>The same parameters are also used when starting <b>smbfs</b> from <i>Workbench</i>. <b>smbfs</b>
 383 will examine its icon tool types and use these in place of the shell command
 384 line.</p>
 385 </ul>
 386
 387 <h2>6. Known problems</h2>
 388
 389 <p>The design of <b>smbfs</b> follows the original file system concept behind the
 390 code which the <i>Sharity-Light</i> file system is based upon. And that is a
 391 Unix file system which differs from Amiga specific file systems in many
 392 ways which can lead to problems which are discussed briefly below:</p>
 393
 394 <ul>
 395 <li><p>Single threaded design</p>
 396
 397 <p>This means that it is not possible for several programs to fairly
 398 share the use of the file system. For example, a program that posts
 399 a long read request can tie up the file system almost exclusively
 400 for itself, and while it is busy all other clients will have to
 401 wait. Same goes for directory scanning.</p>
 402
 403 <li><p>Poor scalability</p>
 404
 405 <p>This is associated with the single threaded design. When several
 406 programs are accessing the file system at the same time, overhead
 407 and unfair sharing of resources will drastically reduce the
 408 performance of the file system.</p>
 409
 410 <li><p>Separation of file data and metadata</p>
 411
 412 <p>This means that the core of the file system treats the contents of
 413 a directory and the data attached to each file inside that
 414 directory as something different. This is a common concept with
 415 Unix file systems, but it is very different with Amiga file systems.
 416 In <b>smbfs</b> this data separation can cause problems when deleting
 417 files from a directory while that directory is being scanned,
 418 such as how this is being done by the <tt>Delete</tt> shell command. The
 419 effects of these problems are that a directory may not be deleted
 420 even though it is empty or that for the same directory the same
 421 file may be reported twice in the listing.</p>
 422
 423 </ul>
 424
 425 <p>While there are no easy solutions for any of these problems, it does not
 426 mean that <b>smbfs</b> is unusable. You just have to be more careful when you
 427 use the file system. For example, if a directory's contents cannot be
 428 deleted due to one of the problems mentioned above, you might want to
 429 retry later.</p>
 430
 431 <p>It should be noted that the problems described above are not inherent
 432 to the original file system design. It's just that transferring that
 433 design to an Amiga file system created the problems.</p>
 434
 435
 436 <h2>7. Credits</h2>
 437
 438 <p>This file system is based upon prior work by Paal-Kr. Engstad, Volker
 439 Lendecke, Mark A. Shand, Donald J. Becker, Rick Sladkey, Fred N. van Kempen,
 440 Eric Kasten and Rudolf Koenig. It is a direct descendant of the
 441 <i>Sharity-Light</i> file system written by Christian Starkjohann.</p>
 442
 443 <p>The password encryption code was lifted from the Samba package. It was
 444 written by Andrew Tridgell and the Samba Team.</p>
 445
 446
 447 <h2>8. Author</h2>
 448
 449 <p>The <i>Sharity-Light</i> source code was adapted and wrapped into an AmigaOS layer
 450 by Olaf `Olsen' Barthel. If you wish to contact me, please send e-mail to the
 451 following address:</p>
 452
 453 <p><tt>obarthel -at- gmx -dot- net</tt></p>
 454
 455 <p>Or, alternatively, you might want to contact me via my postal address:</p>
 456
 457 <p>Olaf Barthel<br>
 458 Gneisenaustr. 43<br>
 459 D-31275 Lehrte<br>
 460 Federal Republic of Germany</p>
 461
 462 <p>If you want to submit a bug report or an enhancement request, please enclose
 463 sufficient information to allow me to make sense of the problem. That includes
 464 debugging logs produced using the <tt>DEBUG</tt> option.</p>
 465
 466 <p>If possible, use the facilities for bug reporting and tracking on the
 467 <a href=http://sourceforge.net/projects/amiga-smbfs><tt>sourceforge.net</tt> web site</a>,
 468 which is the new home for this file system.
 469
 470
 471 <h2>9. Source code</h2>
 472
 473 <p><b>smbfs</b> is distributed under the terms of the GNU General Public License
 474 (version 2). The source code should have accompanied this program; if it
 475 hasn't, please contact the author for a copy.</p>
 476
 477 <p>The program was compiled using the SAS/C 6.58 compiler, with the Roadshow SDK
 478 providing for the TCP/IP stack API header files.</p>
 479 </body>
 480 </html>