OS X Bonjour Naming Guidelines

12 May OS X Bonjour Naming Guidelines

Hostname, Computer Name, Local HostName… Oh My

---

Hostname
A name is a label that is used to distinguish one thing from another. A person’s name, for instance, comprises a set of alphabetic characters that allows a person to be individually addressed. Computers are also named to differentiate one machine from another and to allow for such activities as network communication. Computers have always needed unique addresses to talk to each other. With the advent of the Internet, the requirements for enabling computers to communicate with each other on a network included the concept of the hostname. The hostname began as a simple string of alphanumeric characters (and possibly a hyphen) and has evolved to its current definition, where hostname means a Fully Qualified Domain Name (FQDN) that absolutely and uniquely identifies every computer hooked up to the Internet.

Computer Name
If you have file sharing turned on in Sharing preferences, users on your network can find your Mac listed by its computer name.

For your Mac appears at the top of Sharing preferences.

Local Hostname
Your computer’s local hostname, or Bonjour name, is displayed on your local network so others on the network can connect to your Mac and other functionality like AirDrop, iTunes Sharing, etc. Your computer’s Bonjour name is displayed beneath the computer’s name at the top of Sharing preferences.

The local network name is your computer’s name with “.local” added, and any spaces are replaced with hyphens .

For example, if your computer’s name is My Computer, your local network name is “My-Computer.local.”

Bonjour

---

Bonjour is Apple’s implementation of zero-configuration networking (zeroconf), a group of technologies that includes service discovery, address assignment, and hostname resolution. Bonjour locates devices such as printers, other computers, and the services that those devices offer on a local network using multicast Domain Name System (mDNS) service records.

The software comes built-in with Apple’s OS X and iOS operating systems. Bonjour can also be installed onto computers running Microsoft Windows. Bonjour components may also be included within other software such as iTunes and Safari.

Naming Guidelines

---

Because they are intended to be browsed rather than typed, service instance names can be any Unicode string encoded with UTF-8, up to 63 octets (bytes) in length.

For example, see the following Apple Developer documentation on the web site:

Bonjour Overview – Naming Conventions

 

Bonjour Name Maximum Length – 63 Characters

---

The maximum length of the host name and of the fully qualified domain name (FQDN) is 63 bytes per label and 255 bytes per FQDN. Note – Windows does not permit computer names that exceed 15 characters, and you cannot specify a DNS host name that differs from the NETBIOS host name.

DNS limits the length of each label in RFC 1035 – however, that limit is actually 63. Both in RFC 1035 section 2.3.1 and as clarified in RFC 2181 section 11.

• http://tools.ietf.org/html/rfc1035
• http://tools.ietf.org/html/rfc1035#section-2.3.1
• http://tools.ietf.org/html/rfc2181#section-11

Bonjour Name – Allowed Characters

---

The Internet standards for protocols mandate that component hostname labels may contain only the ASCII letters ‘a’ through ‘z’ (in a case-insensitive manner), the digits ‘0’ through ‘9’, and the hyphen (‘-‘).

-
0123456789
abcdefghijklmnopqrstuvwxyz

The original specification of hostnames in RFC 952, mandated that labels could not start with a digit or with a hyphen, and must not end with a hyphen. However, a subsequent specification (RFC 1123) permitted hostname labels to start with digits. No other symbols, punctuation characters, or white space are permitted.

Setting Bonjour Name

---

To set Bonjour name you can do it manually using the OS X built-in graphical tools.

Select System Preferences -> Sharing, then enter or modify the “Computer Name” text box and press RETURN.

Or if you want a custom Bonjour not based on the computer name, then select the “Edit…” button under the “Computer Name” text box and enter the custom Bonjour name.

Illegal Characters
If you try to use Bonjour illegal characters with the OS X computer name they are converted.

For example, if I tried to set the computer name to “-” (dash), the Bonjour name is converted to “Macintosh.local”

Illegal Length
Or if you try setting a Bonjour name more that 63 character, for example 64 characters, it will not allow you to paste or type more than 63 characters.

preferences.plist
The Bonjour name gets stored in the following property list file:

/Library/Preferences/SystemConfiguration/preferences.plist

In the following key & string:

<dict>
	<key>Network</key>
	<dict>
		<key>BackToMyMac</key>
		<dict/>
		<key>BackToMyMacDSIDs</key>
		<dict/>
		<key>HostNames</key>
		<dict>
			<key>LocalHostName</key>
			<string>My-Computer</string>
		</dict>
	</dict>
	<key>System</key>
	<dict>
		<key>ComputerName</key>
		<string>My Compuiter</string>
		<key>ComputerNameEncoding</key>
		<integer>0</integer>
	</dict>
</dict>

Bonjour Utilities

---

A useful graphical tool to troubleshoot bonjour is Bonjour Browser. It displays all the bonjour services on your local network.

Get Bonjour Name

---

There are multiple command line tools that can get the Bonjour name.

scutil

/usr/sbin/scutil

The “scutil” command (“system configuration utility”) can display basic network information, set the computer hostname, and perform several other tasks. It communicates with configd, read and write from/to the configuration data store.

To get the Bonjour name enter the following command:

scutil –get LocalHostName

For example:

scutil –get LocalHostName my-laptop

systemsetup

/usr/sbin/systemsetup

The “systemsetup” command is a configuration tool for certain machine settings in typically configured in the System Preferences application. The systemsetup command requires at least “admin” privileges to run.

To get the Bonjour name enter the following command:

systemsetup -getlocalsubnetname

For example:

systemsetup -getlocalsubnetname
Local Subnet Name: my-laptop

networksetup

/usr/sbin/networksetup

The “network setup” is a configuration tool for network settings in System Preferences. It does support directly modifying the Bonjour name but can indirectly make modification by changing the computer name.

To get the Computer Name enter the following command:

networksetup -getcomputername

For example:

networksetup -getcomputername
my-laptop

Set Bonjour Name

---

There are multiple command line tools that you can set the Bonjour name.

You can set the Bonjour name using the “scutil” command, for example:

scutil

scutil –set LocalHostName [NAME]

Illegal Characters
If you try to use Bonjour illegal characters, for example trying to set the Bonjour name to “-” (dash), you will get an error using “scutil” command :

scutil --set LocalHostName '-'
SCPreferencesSetLocalHostName() failed: Invalid argument

Illegal Length

Or if you try setting a Bonjour name more that 63 character, for example 64 characters, it will allow it.

scutil --set LocalHostName 0123456789012345678901234567890123456789012345678901234567890123

systemsetup

Or use the “systemsetup” command to set the Bonjour name:

systemsetup -setlocalsubnetname [NAME]

For example:

systemsetup -setlocalsubnetname NewBonjourName
setlocalsubnetname: NewBonjourName

Illegal Characters
If you try to use Bonjour illegal characters, for example set the Bonjour name to “-” (dash), using “systemsetup” command will give an error:

systemsetup -setlocalsubnetname '-'
setlocalsubnetname: Error, - is not a valid name!

Illegal Length
Or if you try setting a Bonjour name more that 63 character, for example 64 characters, it will allow you.

systemsetup -setlocalsubnetname 0123456789012345678901234567890123456789012345678901234567890123

On this issue, I have filed an Apple Bug Report ID 26208725, it you want to reference it and file your own bug report. Also, I have posted the bug into Open Radar ID 5558756960108544

networksetup
Or you could try using the “networksetup” command, but it can only directly set the computer name and not the Bonjour name at all.

networksetup -setcomputername [COMPUTER NAME]

Illegal Length
Or if you try setting a Computer Name more than 63 characters, for example 64 characters, it will display the following error.

networksetup -setcomputername 0123456789012345678901234567890123456789012345678901234567890123
0123456789012345678901234567890123456789012345678901234567890123 is NOT a valid computer name.
** Error: The parameters were not valid.

But, the error isn’t due to length being more than 63 characters, but greater than 31 characters.

For example, a length of 32 characters generate the error:

networksetup -setcomputername 01234567890123456789012345678901
01234567890123456789012345678901 is NOT a valid computer name.
** Error: The parameters were not valid.

But, a length of 31 characters or less will not generate the error:

networksetup -setcomputername 0123456789012345678901234567890

On this issue, I have filed an Apple Bug Report ID 26253116 it you want to reference it and file your own bug report. Also, I have posted the bug into Open Radar ID 4990621907419136

Python Script

---

For our environment, we developed a python script that sets the computer & bonjour name based on the computer hostname and performs sanity checks for maximum length and illegal character, etc. We plan making it available on our Github repository as soon as we have time to remove any site specific references and documentation.