12 May OS X Bonjour Naming Guidelines
Hostname, Computer Name, Local HostName… Oh My
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.
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.
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 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.
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 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.
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.
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”
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.
The Bonjour name gets stored in the following property list file:
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>
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.
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
scutil –get LocalHostName my-laptop
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 Local Subnet Name: my-laptop
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 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 –set LocalHostName [NAME]
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
Or if you try setting a Bonjour name more that 63 character, for example 64 characters, it will allow it.
scutil --set LocalHostName 0123456789012345678901234567890123456789012345678901234567890123
Or use the “systemsetup” command to set the Bonjour name:
systemsetup -setlocalsubnetname [NAME]
systemsetup -setlocalsubnetname NewBonjourName setlocalsubnetname: NewBonjourName
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!
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
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]
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
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.