mirror of
https://github.com/obarthel/amiga-smbfs.git
synced 2025-12-08 14:58:35 +00:00
Replaced the older smbfs.doc file with the Markdown-generated plain text version
This commit is contained in:
obarthel
@@ -1,958 +0,0 @@
|
||||
A SMB file system wrapper for AmigaOS, using the AmiTCP V3 API
|
||||
|
||||
1. What is it?
|
||||
|
||||
This document describes the smbfs program, which implements an SMB file
|
||||
system for AmigaOS.
|
||||
|
||||
This file system can be used to access files made available by file
|
||||
servers which implement the SMBv1 protocol (SMBv1 is also called CIFS,
|
||||
which stands for Common Internet File System), such as Microsoft Windows
|
||||
or any other platform which supports the free Samba product.
|
||||
|
||||
These files can be accessed using shell commands such as List, the
|
||||
Workbench or utilities such as Directory Opus as if the file server were
|
||||
a local disk drive.
|
||||
|
||||
You may find smbfs useful if you want to access a NAS (network-attached
|
||||
storage) drive, or even a Linux file server.
|
||||
|
||||
2. What do you need to get started?
|
||||
|
||||
You need a TCP/IP stack that supports the AmiTCP V3 API, such as Miami,
|
||||
the original free AmiTCP 3.0 release, AmiTCP 4.x, Miami Deluxe, AmiTCP
|
||||
Genesis or Roadshow and the obligatory networking gear. All these items
|
||||
need to be in good shape and properly configured.
|
||||
|
||||
Most important, you need a computer which offers file sharing services
|
||||
using the SMBv1 protocol (instead of being referred to as SMBv1, it may
|
||||
be called CIFS, too).
|
||||
|
||||
It often helps to have Samba installed on your Amiga, too, as this can
|
||||
aid in tracking down bugs and obtaining information which smbfs cannot
|
||||
obtain all by itself.
|
||||
|
||||
Last but not least, you need to be proficient in configuring and using
|
||||
the TCP/IP stack; networking knowledge is definitely assumed.
|
||||
|
||||
The smbfs program requires AmigaOS 2.04 or higher to work.
|
||||
|
||||
3. Preparations
|
||||
|
||||
You need to know which computer’s files you want to share using the
|
||||
smbfs file system. That computer must be known by name or by its IPv4
|
||||
address.
|
||||
|
||||
The name of the computer to connect to cannot be longer than 16
|
||||
characters.
|
||||
|
||||
You need to know which service you want to connect to on the target
|
||||
computer. You can find out which services are available on a certain
|
||||
computer by using the Samba smbclient program.
|
||||
|
||||
For example, if you were to query the services offered by a machine
|
||||
called sourcery you could enter the following:
|
||||
|
||||
And you might get the following information:
|
||||
|
||||
The share name to connect to would be ALL.
|
||||
|
||||
You may need to know which login name and which password is required to
|
||||
connect to the shared disk.
|
||||
|
||||
Very rarely, you would need to know the name of the work group or domain
|
||||
which the file server is a member of. In the example above, the name of
|
||||
the domain would be ARBEITSGRUPPE.
|
||||
|
||||
4. Starting and stopping the file system
|
||||
|
||||
smbfs is an uncommon kind of file system in that you do not use the
|
||||
Mount command to mount it. In fact, smbfs is a program which can be
|
||||
launched from the shell, using command line parameters to tell it which
|
||||
disk should be used. But you can also start it from Workbench: in this
|
||||
case, you would have to put the program’s command line options into icon
|
||||
tool types.
|
||||
|
||||
Please note that if you start smbfs from Workbench, you will not be able
|
||||
to stop smbfs using the Status and Break shell commands.
|
||||
|
||||
4.1. Starting the file system
|
||||
|
||||
By now you should have prepared the following information:
|
||||
|
||||
- Name of the computer to connect to; this would be the file server
|
||||
- Name of the shared disk to connect to
|
||||
- Login name and password (optional)
|
||||
|
||||
That’s basically everything you need to know to continue – unless
|
||||
something goes wrong, but more on that later on.
|
||||
|
||||
Now you can start the file system. For example, to connect to the file
|
||||
server called sourcery and the shared all disk it provides, using the
|
||||
login name PCGuest and not providing any password, you would enter the
|
||||
following:
|
||||
|
||||
This would cause a new device by the name of SMBFS: to be mounted,
|
||||
showing all files and drawers the sourcery server makes available for
|
||||
sharing.
|
||||
|
||||
You can also run the smbfs program in the background, like so:
|
||||
|
||||
Note that this is not recommended because it becomes much harder to tell
|
||||
why the smbfs program did not work correctly (as it invariably will at
|
||||
some point). Any error messages which could help in figuring out what
|
||||
the problem may have been will be lost.
|
||||
|
||||
If you have trouble setting up the smbfs program, first make sure that
|
||||
it works correctly without the Run >NIL: instructions and have a look at
|
||||
any error messages it may produce.
|
||||
|
||||
4.2. Stopping the file system
|
||||
|
||||
How do you “unmount” the file system? Stopping the smbfs program will
|
||||
unmount the file system. This can be accomplished by either hitting the
|
||||
[Ctrl]+C keys or by using the Status shell command and then the Break
|
||||
command.
|
||||
|
||||
For example, the Status shell command may produce the following output:
|
||||
|
||||
Look at the last line describing process number 10: it shows the name of
|
||||
the file system program smbfs and the name of the SMB share it is
|
||||
connected to.
|
||||
|
||||
To stop this file system and effectively unmount it, use the shell Break
|
||||
command; in this case, you would enter Break 10 to stop the file system.
|
||||
|
||||
Note that the smbfs program may not quit immediately. It may have to
|
||||
wait until the last client has released all the resources it obtained
|
||||
from the file system.
|
||||
|
||||
You may have to send more than one Break command to stop the smbfs
|
||||
program.
|
||||
|
||||
4.3. Temporarily disabling the file system
|
||||
|
||||
If, for example, you need to temporarily shut down the network, smbfs
|
||||
will be unable to do its job, at least until the network becomes
|
||||
operational again. In the meantime, Workbench and other programs will
|
||||
keep accessing the file system and may get stuck.
|
||||
|
||||
You can avoid most of these problems by temporarily disabling the file
|
||||
system until it can access the network again. For this to work, you need
|
||||
to start the smbfs program in the shell and use the VOLUMENAME option,
|
||||
which will make a disk icon appear in the Workbench window.
|
||||
|
||||
Please note that smbfs needs to have been started as a shell command
|
||||
rather than from Workbench to allow it to be temporarily disabled and
|
||||
then enabled again.
|
||||
|
||||
To disable the file system, hit the [Ctrl]+D keys or use the Break
|
||||
command (e.g. Break 10 D if smbfs is running as process number 10).
|
||||
|
||||
To re-enable the file system again, hit the [Ctrl]+E keys or use the
|
||||
Break command (e.g. Break 10 E if smbfs is running as process number
|
||||
10).
|
||||
|
||||
5. Startup options
|
||||
|
||||
The smbfs program supports a number of options which control how it
|
||||
works.
|
||||
|
||||
You can enter these options as command line parameters, or, if you start
|
||||
the smbfs program from Workbench, you can set these options as icon tool
|
||||
types.
|
||||
|
||||
Here is how the options look like, in alphabetical order (as command
|
||||
line parameters):
|
||||
|
||||
5.1. Server and authentication options
|
||||
|
||||
In order to use a shared networked file system, you need the following
|
||||
information:
|
||||
|
||||
1. The name or the IPv4 address of the file server and the name of the
|
||||
“share” (file system) you want to access.
|
||||
2. The user name required to access the “share” (file system), unless
|
||||
the server does not need it (“guest” access).
|
||||
3. The password required to access the “share” (file system), unless
|
||||
the server does not need it (“guest” access).
|
||||
|
||||
The parameters relevant for this information are described below.
|
||||
|
||||
5.1.1. SHARE=SERVICE/A
|
||||
|
||||
This parameter takes the form of //server-name/share-name or
|
||||
//server-name:port-number/share-name. You can also use the SMB URI form
|
||||
smb://[[workgroup;]user-name[:password]@]server-name[:port-number]/share.
|
||||
|
||||
For example //sourcery/all, //192.168.0.1/all, //nas:445/files,
|
||||
//nas:microsoft-ds/files, smb://sourcery/all, smb://user@sourcery/all
|
||||
and smb://user:password@sourcery/all would all be valid SHARE
|
||||
parameters.
|
||||
|
||||
In this example, server-name must be either the IPv4 address of the file
|
||||
server to connect to, or the name of the server (note that server names
|
||||
cannot be longer than 16 characters).
|
||||
|
||||
If necessary, you can specify which port number should be used when
|
||||
making the connection. The port number is optional, though. In place of
|
||||
the port (e.g. 445) number you can also use the name of a TCP/UDP
|
||||
service (e.g. microsoft-ds).
|
||||
|
||||
Finally, you need to tell the SMB server which service you want to
|
||||
connect to, which for the smbfs program should be the name of a shared
|
||||
network file system. In the example, the name of the shared network file
|
||||
system would be share-name.
|
||||
|
||||
Unless you use the VOLUMENAME option (e.g. VOLUMENAME=MyData), smbfs
|
||||
will pick a volume name identical to the share name, e.g for
|
||||
//nas:445/pictures the volume name would be pictures and a disk icon
|
||||
named pictures will appear in the Workbench window.
|
||||
|
||||
5.1.2. USER=USERNAME/K
|
||||
|
||||
In order to connect to an SMB share, the server requires that a user
|
||||
name is provided. If you omit the user name, the smbfs program will use
|
||||
GUEST as a replacement.
|
||||
|
||||
If you do provide a user name, it must not be longer than 63 characters.
|
||||
Unless you use the CHANGEUSERNAMECASE=NO option, the name you provide
|
||||
will be translated to all upper case characters.
|
||||
|
||||
You do not need to provide a user name on the command line.
|
||||
Alternatively, you may configure an environment variable whose contents
|
||||
will be used instead. The variable could be set up like this:
|
||||
|
||||
You may also use the smbfs_user environment variable in place of the
|
||||
smbfs_username variable. The two are aliases for one another, but smbfs
|
||||
will read just one of the two.
|
||||
|
||||
5.1.3. PASSWORD/K
|
||||
|
||||
You may not need to provide a password in order to connect to an SMB
|
||||
share. If you omit it, the smbfs program will use an empty password.
|
||||
|
||||
You do need to provide a password on the command line. Alternatively,
|
||||
you may configure an environment variable whose contents will be used
|
||||
instead. The variable could be set up like this:
|
||||
|
||||
Keep in mind that passwords like these really should not be exposed by
|
||||
storing them in environment variables. But then the protocol smbfs uses
|
||||
is almost as insecure as it gets anyway.
|
||||
|
||||
The authentication process only works if the machine you are connecting
|
||||
to knows about the user name and password you want to use. As of this
|
||||
writing, smbfs can only be used for authenticating against a password
|
||||
server that is the same machine as the one on which you wish to access a
|
||||
share.
|
||||
|
||||
5.1.4. CHANGEUSERNAMECASE/K
|
||||
|
||||
Many file servers require that the user name is provided in
|
||||
all-upper-case characters, or they will refuse to grant you access. This
|
||||
is why smbfs defaults to convert the user name to all-upper-case
|
||||
characters.
|
||||
|
||||
However, some file servers such as the Solaris/OpenSolaris/OpenIndiana
|
||||
SMB server require that the user name matches exactly and the conversion
|
||||
to all-upper-case characters will cause trouble.
|
||||
|
||||
In order to disable the user name case-conversion, use the
|
||||
CHANGEUSERNAMECASE=NO option. If you omit the CHANGEUSERNAMECASE option
|
||||
altogether, it will default to CHANGEUSERNAMECASE=YES.
|
||||
|
||||
5.1.5. CHANGEPASSWORDCASE/K
|
||||
|
||||
By default, the password you provide with the PASSWORD option will not
|
||||
be changed before it is used for accessing the server’s shared network
|
||||
file system.
|
||||
|
||||
However, it may be required to change the password to all-uppercase
|
||||
characters before it can be used. If this is necessary, you should
|
||||
either provide the password in this form or use the
|
||||
CHANGEPASSWORDCASE=YES option, which will cause it to be translated to
|
||||
all upper case characters.
|
||||
|
||||
Please note that the CHANGEPASSWORDCASE option will cause the CHANGECASE
|
||||
option to be ignored. If you omit the CHANGEPASSWORDCASE option, then
|
||||
the CHANGECASE option setting will be used instead.
|
||||
|
||||
5.1.6. CHANGECASE/S
|
||||
|
||||
By default, the password you provide with the PASSWORD option will not
|
||||
be changed before it is used for accessing the server’s shared network
|
||||
file system.
|
||||
|
||||
However, it may be required to change the password to all-uppercase
|
||||
characters before it can be used. If this is necessary, you should
|
||||
either provide the password in this form or resort to the CHANGECASE
|
||||
option, which will cause it to be translated to all upper case
|
||||
characters.
|
||||
|
||||
5.1.7. DOMAIN=WORKGROUP/K
|
||||
|
||||
This option may be omitted, in which case the smbfs program will ask the
|
||||
file server about the work group which it is a member of. Should the
|
||||
server fail to respond with this information, the smbfs program will use
|
||||
WORKGROUP as the domain name.
|
||||
|
||||
You should not need to specify the name of the work group or domain
|
||||
which the file server to connect to is a member of. However, if you do
|
||||
need to use it, you must make sure that the name is not longer than 16
|
||||
characters. The name you provide will be translated to all upper case
|
||||
characters.
|
||||
|
||||
You do not need to provide a work group or domain name on the command
|
||||
line. Alternatively, you may configure an environment variable whose
|
||||
contents will be used instead. The variable could be set up like this:
|
||||
|
||||
You may also use the smbfs_domain environment variable in place of the
|
||||
smbfs_workgroup variable. The two are aliases for one another, but smbfs
|
||||
will read just one of the two.
|
||||
|
||||
5.1.8. NETBIOS/S
|
||||
|
||||
Older server software such as Microsoft Windows XP may not respond to
|
||||
the requests of the smbfs program to connect to the shared network file
|
||||
system.
|
||||
|
||||
If the connection attempt fails immediately, you may want to try the
|
||||
NETBIOS switch which tells the smbfs program to use an older protocol
|
||||
when trying to talk to the server.
|
||||
|
||||
5.1.9. CLIENT=CLIENTNAME/K
|
||||
|
||||
The smbfs program will attempt to connect to the file server by
|
||||
providing the name of the computer you connect from.
|
||||
|
||||
In some cases this may be undesirable, as the computer’s name differs
|
||||
from what the file server expects.
|
||||
|
||||
You can use the CLIENT parameter to tell smbfs under which name it
|
||||
should announce itself to the server.
|
||||
|
||||
This parameter is optional and will be translated to all upper case
|
||||
characters; it cannot be longer than 16 characters.
|
||||
|
||||
Please note that the CLIENT parameter will be ignored unless the NETBIOS
|
||||
switch is used, too.
|
||||
|
||||
5.1.10. SERVER=SERVERNAME/K
|
||||
|
||||
smbfs will attempt to connect to the file server by providing the name
|
||||
you specified using the SHARE option.
|
||||
|
||||
In some cases this may be undesirable, as the server’s name differs from
|
||||
what you specified as the share name. You can use the SERVER parameter
|
||||
to tell smbfs under which name it should contact the server.
|
||||
|
||||
This parameter is optional and will be translated to all upper case
|
||||
characters; it cannot be longer than 16 characters.
|
||||
|
||||
Please note that the SERVER parameter will be ignored unless the NETBIOS
|
||||
switch is used, too.
|
||||
|
||||
5.2. File name conversion
|
||||
|
||||
The shared network file system may not be using the same character set
|
||||
as your Amiga, so a translation may be required to allow you to access
|
||||
files and drawers.
|
||||
|
||||
The built-in default translation method should cover the original Amiga
|
||||
character set (ISO-8859-1, also known as ISO-Latin-1), but you have a
|
||||
choice to use a different method.
|
||||
|
||||
Please note that you can only pick one translation method unless you
|
||||
disable translation altogether.
|
||||
|
||||
Also note that file and drawer names which cannot be represented on the
|
||||
Amiga due to lack of a suitable translation will be treated like
|
||||
“hidden” files and drawers. Names which are not safe to use on the
|
||||
Amiga, on account of containing reserved characters, will be “hidden” as
|
||||
well.
|
||||
|
||||
5.2.1. UNICODE/K
|
||||
|
||||
The built-in default translation method is restricted to the part of
|
||||
Unicode which is covered by the ISO-8859-1 character set. It is enabled
|
||||
by default, as if UNICODE=on had been used. You can disable it with
|
||||
UNICODE=off, which completely disables the translation.
|
||||
|
||||
Note: Some Samba versions will return corrupted file and drawer names
|
||||
unless Unicode support is enabled. Names which use only US-ASCII
|
||||
characters appear to be generally safe to use and are unlikely to suffer
|
||||
from corruption.
|
||||
|
||||
5.2.2. CP437/S
|
||||
|
||||
The switch CP437 enables a code page-based translation which works well
|
||||
enough with old Samba versions. “CP437” stands for code page 437, which
|
||||
is what the original IBM-PC would use.
|
||||
|
||||
The CP437 switch disables Unicode support.
|
||||
|
||||
5.2.3. CP850/S
|
||||
|
||||
The switch CP850 enables a code page-based translation which works well
|
||||
enough with old Samba versions. “CP850” stands for code page 850, which
|
||||
is a variant of what the original IBM-PC would use. This variant is
|
||||
intended to be used in Western Europe and is more compatible with the
|
||||
ISO-8859-1 character set than the “CP437” variant.
|
||||
|
||||
The CP850 switch disables Unicode support.
|
||||
|
||||
5.2.4. TRANSLATE=TRANSLATIONFILE/K
|
||||
|
||||
How the individual names are to be translated is determined by the
|
||||
contents of a file name translation table file such as the ones that
|
||||
ship with Workbench in the L:FileSystem_Trans drawer.
|
||||
|
||||
The first 256 bytes of each such file must consist of the mapping of
|
||||
Amiga characters (this would be the ISO-8859-1 character set) to the
|
||||
different character set, and the second 256 characters must describe a
|
||||
mapping back from the different character set to the Amiga.
|
||||
|
||||
In most cases, the L:FileSystem_Trans/INTL.crossdos translation table
|
||||
file should be sufficient.
|
||||
|
||||
To specify which file contains the translation tables, you would use the
|
||||
TRANSLATIONFILE parameter,
|
||||
e.g. TRANSLATIONFILE=L:FileSystem_Trans/INTL.crossdos. However, you
|
||||
might want to try the CP850 switch instead which should produce the same
|
||||
effect.
|
||||
|
||||
The TRANSLATE option disables Unicode support.
|
||||
|
||||
5.3. Performance tuning
|
||||
|
||||
You may be able to put the smbfs program to good use, but overall
|
||||
performance, reliability and memory usage may still be somewhat lacking.
|
||||
These aspects may be tuned with the following parameters.
|
||||
|
||||
5.3.1. CACHE=CACHESIZE/N/K
|
||||
|
||||
The file system attempts to optimize access to the file server when
|
||||
directory entries are being read.
|
||||
|
||||
This information is stored in a cache which by default will hold up to
|
||||
170 entries. Since each entry will require about 255 bytes of storage,
|
||||
the entire 170-entry cache will occupy more than 40 KB of memory.
|
||||
|
||||
You may want to change this requirement, by making the cache smaller or
|
||||
larger using the CACHESIZE parameter. The size of the cache cannot be
|
||||
smaller than 10 entries.
|
||||
|
||||
5.3.2. CACHETABLES/N/K
|
||||
|
||||
The cache can be used only by one directory at a time, which can cause
|
||||
problems if you are trying to delete a complete directory hierarchy,
|
||||
with several subdirectories (and their respective subdirectories). The
|
||||
cache will have to be refilled for each directory currently being
|
||||
processed. Consequently, smbfs will lose track of where it was when it
|
||||
read from the previous directory it was dealing with and must start over
|
||||
again.
|
||||
|
||||
You can mitigate these effects by increasing the number of caches which
|
||||
smbfs may use at a time. By default, only a single cache, for a single
|
||||
directory, will be active (CACHETABLES=1). You can use more directory
|
||||
caches if you want to, but keep in mind that each cache will consume
|
||||
extra memory. If you want to use multiple caches, you might want to
|
||||
reduce the cache size.
|
||||
|
||||
5.3.3. RAISEPRIORITY/S
|
||||
|
||||
The smbfs program can be run at a higher priority than it would normally
|
||||
do (normal would be priority 0), which might increase performance, but
|
||||
raise the system-load, too. If the RAISEPRIORITY switch is used, the
|
||||
smbfs program will run at the same priority as other Amiga file systems
|
||||
do (this would be priority 10).
|
||||
|
||||
5.3.4. TIMEOUT/N/K
|
||||
|
||||
The smbfs program may lose the connection to the server during file
|
||||
system operations. While it will try to reestablish a connection to the
|
||||
server, some time has to pass before it becomes clear that the server
|
||||
connection is no longer working correctly.
|
||||
|
||||
You can set the number of seconds which have to pass before the smbfs
|
||||
program will stop waiting for the server to respond, shut down the
|
||||
connection and try again. For example, TIMEOUT=5 will select a timeout
|
||||
of 5 seconds.
|
||||
|
||||
5.3.5. WRITEBEHIND/S
|
||||
|
||||
The smbfs program can try to improve write performance by not waiting
|
||||
for the server to confirm that all the data just transmitted has in fact
|
||||
been stored. There is a risk involved in that the server may not have
|
||||
been able to store the data, and you will never know about it.
|
||||
|
||||
Please note that the WRITEBEHIND switch has no effect if PROTOCOL=nt1 is
|
||||
used because the smbfs program will then be using a different server
|
||||
write command which does not support the “write behind” functionality.
|
||||
|
||||
5.3.6. READTHRESHOLD/N/K and WRITETHRESHOLD/N/K
|
||||
|
||||
The purpose of smbfs is chiefly to enable you to read and write files
|
||||
stored on a networked computer. To this end smbfs tries its best to
|
||||
squeeze as much performance out of the data transmission as possible.
|
||||
|
||||
Generally, each data transmission consists of two distinct parts. The
|
||||
first part contains information about the data that is being
|
||||
transmitted, such as its size and which file it belongs to. The second
|
||||
part is the data being transmitted.
|
||||
|
||||
smbfs can either send/receive both parts in a single step, or it can
|
||||
send/receive each part separately. If the data is received/sent in a
|
||||
single step, smbfs must spend extra time picking the data apart after it
|
||||
has received it (splitting it up into the information section and the
|
||||
data section), or combine the information and data sections prior to
|
||||
sending them as a single block of data.
|
||||
|
||||
This picking apart/combining comes with a cost because memory contents
|
||||
will have to be copied around. This cost can result in lower
|
||||
performance, which is why smbfs defaults to breaking up the transmission
|
||||
into two steps. Avoiding unnecessary memory copying operations is key to
|
||||
improving network performance on the Amiga.
|
||||
|
||||
However, it is not a given that breaking up the transmission into two
|
||||
steps will always be faster than using a single step, which is where the
|
||||
READTHRESHOLD and WRITETHRESHOLD options come in.
|
||||
|
||||
Transmissions which move large amounts of data tend to benefit
|
||||
significantly from sending/receiving each part of the transmission
|
||||
separately. The same may not be true for small amounts of data being
|
||||
transmitted.
|
||||
|
||||
Through the READTHRESHOLD and WRITETHRESHOLD options you can control the
|
||||
minimum transmission size at which smbfs will always send/receive each
|
||||
part of the transmission separately. In order to make sending small
|
||||
amounts of data more efficient, WRITETHRESHOLD=1500 may be a good
|
||||
choice.
|
||||
|
||||
5.4. Compatibility
|
||||
|
||||
Both the file server and the software running on your Amiga may suffer
|
||||
from compatibility issues. For example, Amiga programs may be unable to
|
||||
deal with file names longer than 30 characters and then crash as a
|
||||
result. Workarounds may be available for some of these issues.
|
||||
|
||||
5.4.1. CASE=CASESENSITIVE/S
|
||||
|
||||
Some file servers treat files and drawers as different if their names
|
||||
differ only in whether individual letters are using upper/lower case
|
||||
characters. For example, on the Amiga we can expect that names such as
|
||||
Work:File1 and Work:file1 would refer to the same file, but you cannot
|
||||
expect this assumption to hold true for shared network file systems.
|
||||
|
||||
For file servers which would see File1 and file1 as different names, you
|
||||
should activate the CASESENSITIVE switch to treat those files as being
|
||||
different.
|
||||
|
||||
There is a catch, though: the AmigaDOS file naming scheme does not
|
||||
follow this model, and you may run into problems when you are trying to
|
||||
use it. For example, in case-sensitive mode, attempting to access a file
|
||||
called FILENAME as filename or Filename will fail; you can access it
|
||||
only under the original name FILENAME.
|
||||
|
||||
By default, the smbfs program does not treat file and drawer names
|
||||
differently which only differ with respect to the case of letters.
|
||||
|
||||
5.4.2. DISABLEEXALL/S
|
||||
|
||||
There are two different methods for reading the names of files and
|
||||
drawers stored in an Amiga volume or drawer.
|
||||
|
||||
The original method (“Examine/ExNext”) will read the individual entries
|
||||
one at a time, and no name may be longer than 107 characters.
|
||||
|
||||
The second method (“ExAll”), introduced with Kickstart 2.0, can deliver
|
||||
more entries and more quickly than the original method. Also, directory
|
||||
entry names may be longer than “just” 107 characters (the smbfs program
|
||||
supports file and drawer names of up to 255 characters).
|
||||
|
||||
The smbfs program supports both methods, but there is a catch: Some
|
||||
Amiga software struggles to handle the number of entries delivered by
|
||||
the “ExAll” method, and names longer than 30 characters are a problem.
|
||||
Such software may malfunction and even crash.
|
||||
|
||||
To avoid problems with such software, the smbfs program can be made to
|
||||
pretend that it does not support the “ExAll” method. Use the
|
||||
DISABLEEXALL switch to disable the “ExAll” method.
|
||||
|
||||
Please note that if the DISABLEEXALL switch is used, the smbfs program
|
||||
will make files and drawers appear to be “hidden” if their names are
|
||||
longer than 107 characters.
|
||||
|
||||
5.4.3. ERROROUTPUT/K
|
||||
|
||||
The smbfs program will try to print error messages in the shell window
|
||||
in a manner which bypasses output redirection. This means that if you
|
||||
decide to discard all the output by sending it to NIL:, then smbfs will
|
||||
still be able to show you error messages.
|
||||
|
||||
Where this is not a useful feature, you can tell the smbfs program to
|
||||
print both normal output and error messages in the same manner: use the
|
||||
ERROROUTPUT=stdout option.
|
||||
|
||||
5.4.4. MAXNAMELEN/N/K
|
||||
|
||||
Some Amiga programs struggle with file and drawer names longer than 30
|
||||
characters. They may malfunction and even crash when the smbfs program
|
||||
delivers them.
|
||||
|
||||
You can tell the smbfs program not to deliver any file or drawer names
|
||||
which are longer than a certain number of characters using the
|
||||
MAXNAMELEN option. For example, MAXNAMELEN=30 would make files and
|
||||
drawers appear to be “hidden” if their names are longer than 30
|
||||
characters.
|
||||
|
||||
5.4.5. MAXTRANSMIT/N/K
|
||||
|
||||
You can fine-tune the size of the transmission buffer which the smbfs
|
||||
program uses when reading and writing files. The server may not have
|
||||
picked a buffer size which suits smbfs well. You can choose a smaller
|
||||
buffer size, if needed.
|
||||
|
||||
The minimum transmission buffer size is 8000 bytes (this is also the
|
||||
default buffer size), and the maximum permitted size is 65535 bytes.
|
||||
|
||||
Please note that the transmission buffer size you asked for may not be
|
||||
accepted by the file server, which may choose to use a much smaller
|
||||
buffer.
|
||||
|
||||
5.4.6. PROTOCOL/K
|
||||
|
||||
The smbfs program talks to the file server using a protocol called
|
||||
SMBv1, using commands and data structures described by the Common
|
||||
Internet File System documentation.
|
||||
|
||||
There are several versions of the SMBv1 protocol in use, and depending
|
||||
upon how old the server software is, smbfs may not work well with the
|
||||
file server.
|
||||
|
||||
It may help if you change the protocol level which the smbfs program
|
||||
uses. The default is PROTOCOL=core which should work well enough with
|
||||
SMB server software available before 2009, and which is particularly
|
||||
suited for use with the Samba server software. How do you know if the
|
||||
Samba server software is being used? Unless you are connecting to a
|
||||
Microsoft Windows server, you can practically assume that Samba will
|
||||
provide the shared network file system.
|
||||
|
||||
The alternative is PROTOCOL=nt1 which might provide better compatibility
|
||||
and performance with Microsoft Windows systems.
|
||||
|
||||
When in doubt, stick with PROTOCOL=core.
|
||||
|
||||
5.4.7. SESSIONSETUP/K
|
||||
|
||||
If the UNICODE=ON option is in effect, the smbfs program may not be able
|
||||
to connect to the server because it expects Unicode text to be used only
|
||||
after the server session has been established.
|
||||
|
||||
With UNICODE=ON the SESSIONSETUP=DELAY option will delay enabling
|
||||
Unicode support until after the session has been established.
|
||||
SESSIONSETUP=NODELAY will enable Unicode support at the earliest
|
||||
possible time instead.
|
||||
|
||||
The default is SESSIONSETUP=DELAY which works both with Samba, and seems
|
||||
to be required for Microsoft Windows systems.
|
||||
|
||||
5.5. Time conversion
|
||||
|
||||
The file server which the smbfs program connects to may not share the
|
||||
exact system time with your Amiga. Typically, it will expect file and
|
||||
drawer modification time information to be recorded in Universally
|
||||
Coordinated Time (UTC), rather than your local time zone (and the
|
||||
effects of daylight savings time).
|
||||
|
||||
You can, and should tell the smbfs program how far the local Amiga time
|
||||
deviates from UTC. By default, the smbfs program will try to use the
|
||||
time zone information configured in the “Locale” preferences. This may
|
||||
not be sufficient, or even the wrong choice.
|
||||
|
||||
5.5.1. TZ=TIMEZONEOFFSET/N/K
|
||||
|
||||
By default, the file system will use the current Locale settings to
|
||||
translate between the local time and the time used by the file server.
|
||||
|
||||
For some configurations, however, this is impractical since the server’s
|
||||
time zone is not configured properly. For these rare cases, you may want
|
||||
to hard-code a certain time zone offset using the TIMEZONEOFFSET option.
|
||||
|
||||
You need to provide the number of minutes to subtract from the local
|
||||
time in order to translate it into the corresponding UTC value. For
|
||||
example, in Central Europe using CET, you would use TZ=60 since CET is
|
||||
one hour ahead of UTC.
|
||||
|
||||
If you use the TIMEZONEOFFSET option, then the smbfs program will ignore
|
||||
the time zone information configured in the “Locale” preferences.
|
||||
|
||||
5.5.2. DST=DSTOFFSET/N/K
|
||||
|
||||
This option can be used to adjust the file date stamps to take local
|
||||
daylight savings time into account.
|
||||
|
||||
The number to specify here is by how many minutes local time has been
|
||||
moved ahead, which is typically 60.
|
||||
|
||||
Note that smbfs does not know when daylight savings time begins and
|
||||
ends. It is up to you to select the correct adjustment value when
|
||||
appropriate.
|
||||
|
||||
5.6. Miscellaneous
|
||||
|
||||
5.6.1. DEVICE=DEVICENAME/K, ADDVOLUME/K and VOLUME=VOLUMENAME/K
|
||||
|
||||
By default, the smbfs program will pick a unique file system device name
|
||||
such as smbfs0: and a volume name which is identical to the share name.
|
||||
For example, for //192.168.0.1/pictures the volume name would be
|
||||
pictures and a disk icon named pictures will appear in the Workbench
|
||||
window.
|
||||
|
||||
You may override the device name which smbfs will use, e.g. the
|
||||
DEVICE=nas: option will try to use nas: if possible. Please note that a
|
||||
device name has to be unique and smbfs may refuse to use it if there is
|
||||
already a file system device of that name.
|
||||
|
||||
You can tell smbfs not to add a volume, which may be useful because the
|
||||
native Amiga Samba port can hang as soon as the file system is started.
|
||||
In such cases, use the ADDVOLUME=NO option. Please note that the
|
||||
ADDVOLUME=NO option will keep smbfs from showing the file system’s disk
|
||||
icon in the Workbench window. If you omit the ADDVOLUME option, smbfs
|
||||
will pretend that ADDVOLUME=YES was in effect.
|
||||
|
||||
If you want to use a specific volume name, use the VOLUME option,
|
||||
e.g. VOLUME=Sourcery:. Otherwise, a volume name derived from the share
|
||||
name will be used instead.
|
||||
|
||||
5.6.2. READONLY/S
|
||||
|
||||
If you want to make sure that the contents of the file system mounted
|
||||
cannot be modified or deleted by mistake, use the READONLY switch. This
|
||||
switch has the same effect as using the Lock shell command. However,
|
||||
this protection against modification will be enabled as soon as the file
|
||||
system has been mounted and the protection cannot be removed with the
|
||||
Lock shell command.
|
||||
|
||||
5.6.3. OMITHIDDEN/S
|
||||
|
||||
When requesting a directory listing, the file server may return some
|
||||
files and drawers tagged as being hidden. By default, smbfs will not
|
||||
treat these “hidden” entries any different from the other directory
|
||||
entries, i.e. they are not hidden from view.
|
||||
|
||||
You can request that the hidden entries should be omitted from directory
|
||||
listings by using the OMITHIDDEN switch.
|
||||
|
||||
Note that even though a file or drawer may be hidden, you should still
|
||||
be able to open and examine it.
|
||||
|
||||
5.6.4. QUIET/S
|
||||
|
||||
When started from shell, the smbfs program will print a message as soon
|
||||
as the connection to the file server has been established.
|
||||
|
||||
If you do not want to see that message displayed, use the QUIET
|
||||
parameter. Please note that the smbfs program may still show error
|
||||
messages.
|
||||
|
||||
5.6.5. SETENV/S
|
||||
|
||||
You may want to stop or disable/re-enabled a currently running smbfs
|
||||
program through the shell Break command, but it may be impractical to
|
||||
figure out which CLI process number is involved.
|
||||
|
||||
This is where the SETENV switch can help. If enabled, a global
|
||||
environment variable will be set which can be used by script files to
|
||||
figure out which CLI process number the respective smbfs program uses.
|
||||
The environment variable will be deleted as soon as the smbfs program
|
||||
exits.
|
||||
|
||||
The environment variable name will be smbfs-process/<device name>,
|
||||
e.g. smbfs-process/smbfs0, and it will contain the CLI process number
|
||||
which the Break command can make use of.
|
||||
|
||||
You can find out which smbfs programs are currently running like so:
|
||||
|
||||
Stopping a program can then be accomplished as follows:
|
||||
|
||||
Note: The SETENV switch only has an effect if you start the smbfs
|
||||
program from the shell.
|
||||
|
||||
5.7. Debugging, diagnostics and bug reports
|
||||
|
||||
The smbfs program may not work as expected, and in order to help
|
||||
figuring out what went wrong, a special debug-enabled version of the
|
||||
program should be supplied along with the “normal” version you are
|
||||
using.
|
||||
|
||||
This special debug-enabled smbfs program (“smbfs.debug”) can produce
|
||||
diagnostic and progress report information which may be stored in a log
|
||||
file.
|
||||
|
||||
5.7.1. DEBUGFILE/K
|
||||
|
||||
If you want to capture the debug output of the smbfs program and have it
|
||||
stored in a file for reference, please state the name of the file here,
|
||||
e.g. DEBUGFILE=ram:smbfs.log.
|
||||
|
||||
If the file already exists, debug output will be appended to it.
|
||||
|
||||
5.7.2. DEBUGLEVEL=DEBUG/N/K
|
||||
|
||||
By default the smbfs program operates in silent mode. It does not report
|
||||
what it is doing, it just tries to respond to file system requests. To
|
||||
obtain debugging output, you may want to use the DEBUG option and
|
||||
specify a debug level greater than 0, e.g. DEBUG=2. The larger the
|
||||
number you specify, the more debugging output will be created.
|
||||
|
||||
Note that unless you state which file the debug output should be written
|
||||
to, all debugging output will be sent to the shell window.
|
||||
|
||||
If you launched the smbfs program from Workbench, debug output will be
|
||||
produced using the operating system’s debug output functionality, which
|
||||
requires that you have a capturing program such as Sashimi running in
|
||||
the background.
|
||||
|
||||
6. Known problems
|
||||
|
||||
The design of smbfs follows the original file system concept behind the
|
||||
code which the Sharity-Light file system is based upon. And that is a
|
||||
Unix file system which differs from Amiga specific file systems in many
|
||||
ways which can lead to problems which are discussed briefly below:
|
||||
|
||||
- Single threaded design
|
||||
|
||||
This means that it is not possible for several programs to fairly share
|
||||
the use of the file system. For example, a program that posts a long
|
||||
read-request can tie up the file system almost exclusively for itself,
|
||||
and while it is busy, all other clients will have to wait. The same goes
|
||||
for directory scanning.
|
||||
|
||||
- Poor scalability
|
||||
|
||||
This is associated with the single threaded design. When several
|
||||
programs are accessing the file system at the same time, overhead and
|
||||
unfair sharing of resources will drastically reduce the performance of
|
||||
the file system.
|
||||
|
||||
- Separation of file data and metadata
|
||||
|
||||
This means that the core of the file system treats the contents of a
|
||||
directory and the data attached to each file inside that directory as
|
||||
something different. This is a common concept with Unix file systems,
|
||||
but it is very different with Amiga file systems. In smbfs this data
|
||||
separation can cause problems when deleting files from a directory while
|
||||
that directory is being scanned, such as how this is being done by the
|
||||
Delete shell command. The effects of these problems are that a directory
|
||||
may not be deleted even though it is empty or that for the same
|
||||
directory the same file may be reported twice in the listing.
|
||||
|
||||
While there are no easy solutions for any of these problems, it does not
|
||||
mean that smbfs is unusable. You may have to be more careful when using
|
||||
the file system. For example, if a directory’s contents cannot be
|
||||
deleted due to one of the problems mentioned above, you might want to
|
||||
try again later.
|
||||
|
||||
It should be noted that the problems described above are not inherent to
|
||||
the original file system design. It’s just that transferring that design
|
||||
to an Amiga file system created the problems.
|
||||
|
||||
7. Notes on smbfs version 2.1
|
||||
|
||||
smbfs is ultimatively based upon code created by reverse-engineering the
|
||||
SMB protocol. This effort led to the smbfs kernel module which was
|
||||
included with Linux 2.0.1 in 1995.
|
||||
|
||||
Subsequent work went into modifying the code, allowing it to be used as
|
||||
a file system on NeXTSTEP and various Unix versions (e.g. NetBSD,
|
||||
Solaris and IRIX) in the form of the 1996/1997 Sharity and Sharity-Light
|
||||
file systems. The Amiga smbfs is a port of Sharity-Light.
|
||||
|
||||
Because smbfs is based upon reverse-engineered code, it was always
|
||||
difficult to maintain it, even for minor changes needed to fix small
|
||||
bugs or to improve overall compatibility. How smbfs went about when
|
||||
communicating with a remote file server, and why, would remain unclear
|
||||
because the documentation which could shed some light on these matters
|
||||
was unavailable until around 2009/2012.
|
||||
|
||||
When I picked up development of smbfs again in 2016, I decided that I
|
||||
needed to know more about how the file system is supposed to work if I
|
||||
were ever going to be able to make robust changes to the code.
|
||||
|
||||
This is what led me to collecting more than 30 MB of documentation on
|
||||
SMBv1/CIFS, NetBIOS and the way in which Microsoft operating systems
|
||||
implemented these over the years.
|
||||
|
||||
What insights I managed to gain from this collection allowed me to
|
||||
update and rewrite the smbfs code so that its functionality and data
|
||||
structures now reflect the official SMBv1/CIFS documentation. The idea
|
||||
is that with these changes in place, future maintenance and enhancements
|
||||
should be easier to perform and to add. I wish I would not have needed
|
||||
to write my own SMB protocol disassembler and stumble through so many
|
||||
blind alleys, but this is how it goes with SMBv1/CIFS…
|
||||
|
||||
Now you know why it took almost two years to get from smbfs version 1.80
|
||||
to version 2.1.
|
||||
|
||||
8. Credits
|
||||
|
||||
The smbfs file system is based upon prior work by Pål-Kristian Engstad,
|
||||
Volker Lendecke, Mark A. Shand, Donald J. Becker, Rick Sladkey, Fred N.
|
||||
van Kempen, Eric Kasten and Rudolf König. It is a direct descendant of
|
||||
the Sharity-Light file system written by Christian Starkjohann.
|
||||
|
||||
Versions including 1.80 and beyond incorporate changes from the MorphOS
|
||||
smbfs version 50.3, which was kindly provided by Frank Mariak. The
|
||||
individual changes came from Harry Sintonen, David Gerber and Frank
|
||||
Mariak.
|
||||
|
||||
The password encryption code was lifted from the Samba package. It was
|
||||
written by Andrew Tridgell and the Samba Team.
|
||||
|
||||
The great majority of changes and bug fixes which found their way into
|
||||
version 2.1 are due to Hubert Maier, who patiently tested the various
|
||||
attempts to address the problems he reported.
|
||||
|
||||
Renaud Schweingruber kicked off the last stretch of the version 2.1
|
||||
development work during 2018, encouraging me to complete the work I had
|
||||
begun.
|
||||
|
||||
Much of the testing and feedback during the development of version 2.1
|
||||
in Summer 2018 was performed by and came from the www.a1k.org forum
|
||||
members, who put each test version through its paces, on hardware which
|
||||
I would have never been able to test it with. The rapid testing and
|
||||
feedback finally allowed version 2.1 to be released in 2018.
|
||||
|
||||
Robert Kidd provided detailed information on how to make the smbfs
|
||||
client/server authentication work with OpenSolaris/OpenIndiana. The
|
||||
changes made allow smbfs not just to work better with OpenSolaris, but
|
||||
with other SMBv1/CIFS server software, too.
|
||||
|
||||
9. Author
|
||||
|
||||
The Sharity-Light source code was adapted, wrapped into an AmigaOS
|
||||
layer, subsequently debugged and enhanced by Olaf Barthel. If you wish
|
||||
to contact me, you can reach me at:
|
||||
|
||||
Olaf Barthel
|
||||
Gneisenaustr. 43
|
||||
D-31275 Lehrte
|
||||
|
||||
Or via e-mail:
|
||||
|
||||
obarthel [at] gmx.net
|
||||
|
||||
If you want to submit a bug report or an enhancement request, please
|
||||
enclose sufficient information to allow me to make sense of the problem.
|
||||
That includes debugging logs produced using the DEBUG and DEBUGFILE
|
||||
options.
|
||||
|
||||
10. Source code
|
||||
|
||||
smbfs is distributed under the terms of the GNU General Public License
|
||||
(version 2). The source code should have accompanied this program; if it
|
||||
hasn’t, please contact the author for a copy.
|
||||
|
||||
The program was compiled using the SAS/C 6.58 compiler, with the
|
||||
Roadshow SDK providing for the TCP/IP stack API header files.
|
||||
Reference in New Issue
Block a user