Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       AppleVolumes.default, AppleVolumes.system, AppleVolumes - Configuration
       file used by afpd(8) to determine the shares made available through AFP
       and specify file	name extension mappings.


       /usr/local/etc/AppleVolumes.system and one of
       /usr/local/etc/AppleVolumes.default, ~/AppleVolumes, ~/.AppleVolumes,
       ~/applevolumes, or ~/.applevolumes are the configuration	files used by
       afpd to determine what portions of the file system will be shared via
       Apple Filing Protocol, as well as their behaviour.

       Any line	not prefixed with # is interpreted. Newline escaping is
       supported. The configuration lines are composed like:

       path [ volume name ] [ options ]

       .extension [ type [ creator ] ]

       The path	name must be a fully qualified path name, or a path name using
       either the ~ shell shorthand or any of the substitution variables,
       which are listed	below.

       The volume name is the name that	appears	in the Chooser ot the "connect
       to server" dialog on Macintoshes	to represent the appropriate share. If
       volumename is unspecified, the last component of	pathname is used. No
       two volumes may have the	same name. If there are	spaces in the name, it
       should be in quotes (i.e. "File Share").	The volume name	cannot contain
       the ':' character. The volume name is mangled if	it is very long. Mac
       codepage	volume name is limited to 27 characters. UTF8-MAC volume name
       is limited to -volnamelen parameter in afpd.conf

	   Each	volume has to be configured on a single	line. Though newline
	   escaping is supported.

       The leading-dot lines specify file name extension mappings. The
       extension '.' sets the default creator and type for otherwise untyped
       Unix files.

	   File	name extension mapping is useful for Mac OS 9 and earlier. But
	   it should not use for Mac OS	X.

       It is possible to specify default options for all volumes with a
       :DEFAULT: line preceeding these volume definitions:

       Example.	:DEFAULT: configuration	line

	   :DEFAULT: options:upriv,usedots dbpath:/var/dbd/AppleDB/$v dperm:0775 fperm:0664

       The possible options and	their meanings are:

	   Specify the format of the metadata files, which are used for	saving
	   Mac resource	fork as	well. Earlier versions used AppleDouble	V1,
	   the new default format is V2. Starting with Netatalk	2.0, the
	   scheme MacOS	X 10.3.x uses, is also supported.

	       adouble:osx cannot be treated normally any longer. Its only aim
	       was to temporarely share	eg. FAT32 formatted FireWire
	       harddrives written on a Macintosh with afpd. Apple's metadata
	       scheme lacks several essential features,	so using it on the
	       server's	side will break	both CNIDs and MacOS 9 compatibility.
	       AppleDouble file	of Mac OS X 10.6 is incompatible to V1 and V2.

       volsizelimit:size in MiB
	   Useful for TimeMachine: limits the reported volume size, thus
	   preventing TM from using the	whole real disk	space for backup.
	   Example: "volsizelimit:1000"	would limit the	reported disk space to
	   1 GB.  IMPORTANT: This is an	approximated calculation taking	into
	   accout the contents of TM sparsebundle images. Therefor you MUST
	   NOT use this	volume to store	other content when using this option,
	   because it would NOT	be accounted. The calculation works by reading
	   the band size from the Info.plist XML file of the sparsebundle,
	   reading the bands/ directory	counting the number of band files, and
	   then	multiplying one	with the other.

	   The allow option allows the users and groups	that access a share to
	   be specified. Users and groups are specified, delimited by commas.
	   Groups are designated by a @	prefix.	Example:

	   The deny option specifies users and groups who are not allowed
	   access to the share.	It follows the same format as the allow

       allowed_hosts:[IP host address/IP netmask bits[,	... ]]
	   Only	listed hosts and networks are allowed, all others are
	   rejected. The network address may be	specified either in
	   dotted-decimal format for IPv4 or in	hexadecimal format for IPv6.

	   Example: allowed_hosts:,,2001:0db8:1234::/48

       denied_hosts:[IP	host address/IP	netmask	bits[, ...]]
	   Listed hosts	and nets are rejected, all others are allowed.

	   Example: denied_hosts: 192.168.100/24,,2001:db8::1428:57ab

	   set the CNID	backend	to be used for the volume, default is [dbd]
	   available schemes: [dbd last	tdb]

	   Sets	the database information to be stored in path. You have	to
	   specifiy a writable location, even if the volume is read only.

	   Query this servername or IP address (default:localhost) and port
	   (default: 4700) for CNIDs. Only used	with CNID backend "dbd". This
	   option here overrides any setting from afpd.conf:cnidserver.

	   Specify how Extended	Attributes are stored.	auto is	the default.

	       Try sys (by setting an EA on the	shared directory itself),
	       fallback	to ad. Requires	writeable volume for perfoming test.
	       options:ro overwrites auto with none. Use explicit ea:sys|ad
	       for read-only volumes where appropiate.

	       Use filesystem Extended Attributes.

	       Use files in .AppleDouble directories.

	       No Extended Attributes support.

	   specifies the mac client codepage for this Volume, e.g.
	   "MAC_ROMAN",	"MAC_CYRILLIC".	If not specified the setting from
	   afpd.conf is	inherited. This	setting	is only	required if you	need
	   volumes, where the mac codepage differs from	the one	globally set
	   in afpd.conf.

	   This	allows multiple	options	to be specified	in a comma delimited
	   format. The available options are:

	       Use fast	CNID database namesearch instead of slow recursive
	       filesystem search. Relies on a consistent CNID database,	ie
	       Samba or	local filesystem access	lead to	inaccurate or wrong
	       results.	Works only for "dbd" CNID db volumes.

	       Enable Time Machine suport for this volume.

	       Use with	usedots: make dot files	invisible.

	       Try to force ACL	unawareness on the client.

	       Limit disk size reporting to 2GB. This can be used for older
	       Macintoshes using newer Appleshare clients.

	       a non-zero return code from preexec close the volume being
	       immediately, preventing clients to mount/see the	volume in

	       Specifies the share as being read only for all users. The
	       .AppleDB	directory has to be writeable, you can use the -dbpath
	       option to relocate it. Overwrites ea:auto with ea:none

	       a non-zero return code from root_preexec	closes the volume
	       immediately, preventing clients to mount/see the	volume in

	       use AFP3	unix privileges. This should be	set for	OS X clients.
	       Starting	with Netatalk 2.1 it's part of the default config
	       :DEFAULT: line. See also: perm|fperm|dperm.

	       Don't do	:hex translation for dot files.	note: when this	option
	       gets set, certain file names become illegal. These are .Parent
	       and anything that starts	with .Apple. See also invisibledots.

	       Follow symlinks on the server.

	   This	option allows you to set a volume password, which can be a
	   maximum of 8	characters long	(using ASCII strongly recommended at
	   the time of this writing).

	   Add(or) with	the client requested permissions: perm affects files
	   and directories, fperm is for files only, dperm is for directories
	   only. Use with options:upriv.

	   Example. Volume for a collaborative workgroup

	       /path/to/volume "Workgroup" options:upriv dperm:0770 fperm:0660

	   set perm mask. Use with options:upriv.

	   command to be run when the volume is	mounted, ignored for user
	   defined volumes

	   command to be run when the volume is	closed,	ignored	for user
	   defined volumes

	   command to be run as	root when the volume is	mounted, ignored for
	   user	defined	volumes

	   command to be run as	root when the volume is	closed,	ignored	for
	   user	defined	volumes

	   Allows certain users	and groups to have read-only access to a
	   share. This follows the allow option	format.

	   Allows certain users	and groups to have read/write access to	a
	   share. This follows the allow option	format.

       veto:[vetoed names]
	   hide	files and directories,where the	path matches one of the	'/'
	   delimited vetoed names. The veto string must	always be terminated
	   with	a '/', eg. "veto1/", "veto1/veto2/".

	   specifies the volume	codepage, e.g. "UTF8", "UTF8-MAC",
	   "ISO-8859-15". Defaults to "UTF8".

       You can use variables in	both volume path and volume name.

	1. if you specify an unknown variable, it will not get converted.

	2. if you specify a known variable, but	that variable doesn't have a
	   value, it will get ignored.

       The variables which can be used for substitutions are:


	   client's ip or appletalk address

	   volume pathname on server

	   full	name (contents of the gecos field in the passwd	file)

	   group name


	   client's ip,	without	port

	   server name (this can be the	hostname)

	   user	name (if guest,	it is the user that guest is running as)

	   volume name (either ADEID_NAME or basename of path)

	   appletalk zone (may not exist)

	   prints dollar sign ($)

       Example.	Using variable substitution when defining volumes

	   /home/groups/$g "Groupdir for $g"
	   ~ "$f is the	best one"

       We define "groupdirs" for each primary group and	use a personalized
       server name for homedir shares.

       The AFP protocol	mostly refers to files and directories by ID and not
       by name.	Netatalk needs a way to	store these ID's in a persistent way,
       to achieve this several different CNID backends are available. The CNID
       Databases are by	default	located	in the .AppleDB	folder in the volume

	   "Concurrent database", backend is based on Sleepycat's Berkely DB.
	   With	this backend several afpd deamons access the CNID database
	   directly. Berkeley DB locking is used to synchronize	access,	if
	   more	than one afpd process is active	for a volume. The drawback is,
	   that	the crash of a single afpd process might corrupt the database.

	   Access to the CNID database is restricted to	the cnid_metad daemon
	   process.  afpd processes communicate	with the daemon	for database
	   reads and updates. If built with Berkeley DB	transactions the
	   probability for database corruption is practically zero, but
	   performance can be slower than with cdb

	   This	backend	is an exception, in terms of ID	persistency. ID's are
	   only	valid for the current session. This is basically what afpd did
	   in the 1.5 (and 1.6)	versions. This backend is still	available, as
	   it is useful	for e.g. sharing cdroms.

	   Warning: It is NOT recommended to use this backend for volumes
	   anymore, as afpd now	relies heavily on a persistent ID database.
	   Aliases will	likely not work	and filename mangling is not

       Even though ./configure --help might show that there are	other CNID
       backends	available, be warned those are likely broken or	mainly used
       for testing. Don't use them unless you know what	you're doing, they may
       be removed without further notice from future versions.

       With OS X Apple introduced the AFP3 protocol. One of the	most important
       changes was that	AFP3 uses unicode names	encoded	as UTF-8 decomposed.
       Previous	AFP/OS versions	used codepages,	like MacRoman,
       MacCentralEurope, etc.

       afpd needs a way	to preserve extended macintosh characters, or
       characters illegal in unix filenames, when saving files on a unix
       filesystem. Earlier versions used the the so called CAP encoding. An
       extended	character (>0x7F) would	be converted to	a :xx sequence,	e.g.
       the Apple Logo (MacRoman: 0XF0) was saved as :f0. Some special
       characters will be converted as to :xx notation as well.	'/' will be
       encoded to :2f, if usedots is not specified, a leading dot '.' will be
       encoded as :2e.

       This version now	uses UTF-8 as the default encoding for names. Special
       characters, like	'/' and	a leading '.' will still be CAP	style encoded

       The -volcharset option will allow you to	select another volume
       encoding. E.g. for western users	another	useful setting could be
       -volcharset ISO-8859-15.	 apfd will accept any iconv(1) provided
       charset.	If a character cannot be converted from	the mac	codepage to
       the selected volcharset,	afpd will save it as a CAP encoded character.
       For AFP3	clients, afpd will convert the UTF-8 character to -maccharset
       first. If this conversion fails,	you'll receive a -50 error on the mac.

       Note: Whenever you can, please stick with the default UTF-8 volume

       To use a	volume created with an earlier afpd version, you'll have to
       specify the following options:

       Example.	use a 1.x style	volume

	   /path/to/volume "Volname" adouble:v1	volcharset:ASCII

       In case you used	an NLS you could try using a compatible	iconv charset
       for -volcharset.

       Example.	use a 1.x style	volume,	created	with maccode.iso8859-1

	   /path/to/volume "Volname" adouble:v1	volcharset:ISO-8859-1

       You should consider converting old style	volumes	to the new UTF-8/AD2
       format. The safest way to do this, is to	create a new volume with the
       default options and copy	the files between this volumes with a mac.

       Note: Using above example options will allow you	to downgrade to	1.x
       netatalk	again.

       Note: Some 1.x NLS files	used non standard mappings, e.g.
       maccode.iso8859-1.adapted. Three	1.x CAP	double-byte maccharsets	are
       incompatible to netatalk	2.x; "MAC_CHINESE_TRAD", "MAC_JAPANESE"	and
       "MAC_KOREAN". These are not supported anymore. You'll have to copy the
       contents	of those volumes files to a Mac	and then back to the netatalk
       server, preferably to an	UTF-8 volume.

       The following options should only be used after serious consideration.
       Be sure you fully understood the, sometimes complex, consequences,
       before using them.

	   The casefold	option handles,	if the case of filenames should	be
	   changed. The	available options are:

	   tolower - Lowercases	names in both directions.

	   toupper - Uppercases	names in both directions.

	   xlatelower -	Client sees lowercase, server sees uppercase.

	   xlateupper -	Client sees uppercase, server sees lowercase.

	   This	allows multiple	options	to be specified	in a comma delimited
	   format. The available options are:

	       The underlying filesystem is case insensitive (only tested with
	       JFS in OS2 mode).

	       Enables crlf translation	for TEXT files,	automatically
	       converting macintosh line breaks	into Unix ones.	Use of this
	       option might be dangerous since some older programs store
	       binary data files as type "TEXT"	when saving and	switch the
	       filetype	in a second step.  Afpd	will potentially destroy such
	       files when "erroneously"	changing bytes in order	to do line
	       break translation.

	       Allows a	volume to be declared as being a "dropbox." Note that
	       netatalk	must be	compiled with dropkludge support for this to
	       function.  Warning: This	option is deprecated and might not
	       work as expected.

	       same as "dropbox".

	       Forces filename restrictions imposed by MS WinXX.  Warning:
	       This is NOT recommened for volumes mainly used by Macs. Please
	       make sure you fully understand this option before using it.

		   This	option breaks direct saving to netatalk	volumes	from
		   some	applications, i.e. OfficeX.

	       Forces afpd to not create .AppleDouble directories unless
	       macintosh metadata needs	to be written. This option is only
	       useful if you want to share files mostly	used NOT by macs,
	       causing afpd to not automatically create	.AppleDouble subdirs
	       containing AD header files in every directory it	enters (which
	       will it do by default).

	       In case,	you save or change files from mac clients, AD metadata
	       files have to be	written	even in	case you set this option. So
	       you can't avoid the creation of .AppleDouble directories	and
	       its contents when you give macs write access to a share and
	       they make use of	it.

	       Try to avoid noadouble whenever possible.

	       If set afpd doesn't store the ID	information in AppleDouble V2
	       header files. As	these IDs are used for caching and as a
	       database	backup,	this option normally shouldn't be set.

	       always use 0 for	device number, helps when the device number is
	       not constant across a reboot, cluster, ...

	       don't advertise createfileid, resolveid,	deleteid calls.

	       Disables	:hex translations for anything except dot files. This
	       option makes the	'/' character illegal.

	       don't stat volume path when enumerating volumes list, useful
	       for automounting	or volumes created by a	preexec	script.

	       Provides	compatibility with Apple II clients. (legacy)

       Example.	Extension is jpg. Type is "JPEG". Creator is "ogle".

	   .jpg	"JPEG" "ogle"

       Example.	Extension is lzh. Type is "LHA ". Creator is not defined.

	   .lzh	"LHA "

       afpd.conf(5), afpd(8), cnid_metad(8)

Netatalk 3.0			  27 Dez 2012		 APPLEVOLUMES.DEFAU(5)


Want to link to this manual page? Use this URL:

home | help