OS X Bonjour Naming Guidelines

OS X Bonjour Naming Guidelines

Hostname, Computer Name, Local HostName… Oh My


Wizard of Oz

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.

System Preferences - Computer Name Example

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.

System Preferences - Bonjour Name Example

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.”

System Preferences - Bonjour Name Edit Example

Bonjour


adele-hello-its-me

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 Names - Apple Developer

 

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.

System Preferences - Bonjour Name Edit Example

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”

bonjour illegal name example

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.

bonjour browser

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

Open Radar ID 4990621907419136 Example

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

Open-Radar-ID-4990621907419136-Example

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.

4 Comments
  • EricHeitzman
    Posted at 21:05h, 01 February Reply

    This is an excellent write-up, thank you for this!

    I work in a corporate environment where the IT department wants computer names to match the “Asset Tag” which is a difficult-to-remember long string of random letters and numbers. But I wanted a “normal” name for AirDrop, File Sharing, Printing, SSH, and so on.

    In the macOS GUI (System Preferences–>Sharing) the “Bonjour Name” is set to match the “Computer Name” automatically, but your article explained how to make them different:

    You will need local Administrator privileges.
    Open Terminal:

    I set the hostname to Asset Tag to make my IT department happy:
    sudo scutil –set LocalHostName FUC43765OJN233

    I set a memorable and usable “Bonjour Name”:
    sudo systemsetup -setlocalsubnetname Frodo

    • Richard Glaser
      Posted at 23:34h, 01 February Reply

      Hi Eric:

      Great, I am glad you found the post useful. It’s a little old and probably could revisit it and update the post if it is beneficial to others.

      • Eric Heitzman
        Posted at 23:59h, 01 February Reply

        The information still seems accurate to me, but you might want to document this useful feature in the “Sharing” Preferences pane called “Use dynamic global hostname.” I could be mistaken, but it looks like this setting might allow macOS to use a dynamic DNS provider.

        Here’s the setting:
        1. Go to System Preferences –> Sharing –> in the “Computer Name” panel click the “Edit…” button.
        2. In the dialog box that appears, there is a checkbox labeled “Use dynamic global hostname”.

        Here’s the (somewhat meager) documentation:
        https://support.apple.com/guide/?platform=mac&product=mac-help&vanityname=use-a-dynamic-global-hostname-on-mac&version=11.0&locale=en_US&topicid=MH27452&type=ddm&platformOSVersion=11.0

        That documentation also mentions, “If your service provider supports Wide-Area Bonjour registrations, you can also select ‘Advertise services in this domain using Bonjour.’ to advertise your computer’s active sharing services in this domain.”

        I haven’t looked into Wide-Area Bonjour registrations, but maybe that allows Bonjour services like AirDrop and Printing to be accessible across a larger network than just the local subnet.

        Anyway, thank you for your good work – it helped me solve my problem.

        • Richard Glaser
          Posted at 11:13h, 02 February Reply

          Hi Eric:

          Ok, thanks for the feedback, I will add it to my future to-do’s when I have the bandwidth to focus on it.

Leave a Reply