Hands-Free Server Discovery:

Perforce and Zero-

Configuration Networking
Michael Bishop, Perforce Software

This paper refers to functionality

that is still under development
and is not supported as of the
2008.1 Perforce Server release.

Perforce and Zeroconf 1 Perforce Software ©2008

Overview............................................................................ 3
The Zeroconf technology............................................. 3
DNS

Multi-cast DNS

Advertising Meta-data

How Perforce uses Zeroconf....................................... 6

Advertising a Service

Browsing for Perforce Servers

The New P4PORT

Putting it All Together

Writing code to find Perforce services...................10

ClientAPI Changes

Writing Browsing Code

Assumptions About P4PORT

Ideas for the future..................................................... 12

Appendices....................................................................... 13
Appendix A: Perforce service-types and TXT Records

Appendix B: Useful Links and Documentation

Perforce and Zeroconf 2 Perforce Software ©2008

1. Overview
Perforce received requests from users and administrators to be able to monitor and
browse for servers on the network. Zero-Configuration Networking (or “Zeroconf”) is
a networking standard that succinctly addresses this problem. This document provides
an overview of Zeroconf, how Perforce can use it, and how developers can write
software to take advantage of it.

2. The Zeroconf technology

Zeroconf offers your users the ability to never have to remember a networking
address. Instead, they can simply browse the network for available services.

DNS
Zeroconf works by resting atop standard DNS queries. Software on your computer
has the ability to “advertise” that it’s listening on a port. To make this advertisement,
the software installs standard DNS records in a DNS server. Included in the
advertisement is:
• the address of the advertising machine
• the port that is waiting for a connection
• The “service-type” of the listening connection, (ie. Is it a printer? Web-server?)
• A Human-Readable Name associated with the advertisement.

I've got a webserver

listening on port 8080
called "Personal Web"
DNS
acme.com

pub.acme.com

Perforce and Zeroconf 3 Perforce Software ©2008

 Other software can query the DNS server to browse for the advertisements of a
specific service-type. With this configuration, it’s possible for software to discover
other software.

goof.acme.com
I know one at pub.acme.com:8080
called "Personal Web"
Do you know any
webservers?

I've got a webserver

listening on port 8080
called "Personal Web"
DNS
acme.com

pub.acme.com

At this point, we already have something very interesting. All the infrastructure is in
place for users to browse for specific types of services (in this case “webservers”).
Also interesting is that the identifier of a service is no longer a network address. It has
been replaced by a Human-Readable Name.

Multi-cast DNS
While Zeroconf can talk to standard DNS servers (called “wide-area service
discovery”), the most common use of Zeroconf is to rest atop a special type of DNS
server called a “multi-cast” DNS server. A multi-cast DNS (mDNS) server is a
distributed DNS server that exists simply because all the machines on a local subnet
run a special daemon. The daemons collectively create a DNS server that is
responsible for a new top-level domain called “.local”.
With multi-cast DNS, every machine has a domain name and an IP address, even in
the absence of a standard DNS server. Daemons running on either sides of a router
can’t discover each other, so the .local domain is restricted to the local-link.

= the daemon

goof.local
(also goof.acme.com)

PowerBook G4

papasmurf.local
DNS (no other address)

.local

pub.local
(also pub.acme.com)

Perforce and Zeroconf 4 Perforce Software ©2008

 Client software will likely never expose this infrastructure, but it’s useful to have a
general idea of how it works.
Let’s revisit an earlier diagram but this time with multi-cast DNS...

goof.local
I know one at pub.local:8080
called "Personal Web"
Do you know any
I've got a webserver webservers?
listening on port 8080
called "Personal Web"

DNS
.local

pub.local

Perforce is currently developing for this local (mDNS) Zeroconf configuration.

Advertising Meta-data
Advertisements can include one more piece of data which is an arbitrary set of key-
value pairs called “TXT Records”. This is a very powerful construct because each
service-type can have their own standard for what TXT Record keys are exported. For
instance, a printer service may export the physical location of the printer in a TXT
Record using the key “location”.
I've got a printer listening on port 478
called "Gutenberg"
location="Next to the Kitchen"

DNS
.local
gutenberg.local

The Perforce Server will use these TXT records to include descriptions of servers in
its advertisements.

Perforce and Zeroconf 5 Perforce Software ©2008

3. How Perforce uses Zeroconf
Zeroconf can be used by Perforce to advertise, and browse for servers, and to resolve
P4PORT that have Human-Readable Names as their values.

Advertising a Service
Perforce has defined a set of standard flags intended to work for p4d, p4p, p4web, and
p4ftp.

Flags
–0 The “advertise” flag. (“Dash-zero”)
Advertising is not on by default, so this flag must be set to
allow other clients to browse for the service. Without the name
flag (described below), a default name (most likely the machine
name) will appear in browse lists.
–In <name> The “name” flag.
This flag assigns a human-readable name to a service. When
used with Zeroconf, browsing clients will see it in a list. p4d
will also output this value when called with the command p4
info -ztag.

<name> can be up to 63 bytes of UTF-8 encoded text. Non-ascii

characters and spaces are allowed. The <name> value will likely
appear in a graphical list, where users will choose it, so longer
descriptive names are better.
Additionally, the <name> value will become the unique name
that defines the server. Since (as we will see later), it’s possible
to store this name as your P4PORT variable, it is best to choose a
name and not change it.
–Id <desc> The “description” flag.
Allows a description to be tied to the server. When used with
Zeroconf, browsing software can display a description beside
the name to give detailed information about the server. Again,
any UTF-8 characters are allowed.

Example
p4d -0 –In “Skunkworks Group” -Id “The server devoted to internal
secret projects”

In this example, a server named “Skunkworks Group” advertises with

Zeroconf including the description “The server devoted to internal secret
projects”

Perforce and Zeroconf 6 Perforce Software ©2008

 Browsing for Perforce Servers
Starting a Perforce client (such as P4V) will allow a user to choose available servers
from the network. Developers can also write code that can find Perforce servers (see -
“Writing code to find Perforce services”)

P4D
-0
-In "Main Development"
-Id "Development only. Check your
core dumps into the debugging Main Development Development only. Check your core dumps in
Perforce 日本 メーン・デバ・サーバー
server"

P4D
-0
-In "Perforce 日本"
-Id "メーン・デバ・サーバー"

Servers Sample GUI Browser

The New P4PORT

The P4PORT variable has been traditionally formatted as host:port. With Zeroconf, a
Human-Readable Name can be used in place of this construct. The name will be
resolved to a host:port just before the client makes a connection to the server. In the
example below, note the absence of any host:port combination.

Example
> p4d -0 –In “Test Server” &

Perforce Server starting...

> p4 -p “Test Server” info

User name: mbishop

Client name: mbishop-main
Client host: MichaelBook.local
Client root: /Users/mbishop/dev/perforce_1666/main
Current directory: /Users/mbishop/dev/perforce_1666/main
Client address: 127.0.0.1:49762
Server address: localhost:1666
Server root: /Users/mbishop/dev/PerforceDB
Server date: 2008/03/13 21:59:46 -0700 PDT
Server version: P4D/DARWIN80X86/2007.2/136993 (2007/10/18)
Server license: none

Perforce and Zeroconf 7 Perforce Software ©2008

 Also note that the Perforce Server can still be reached with the traditional host:port
combination.

Example
> p4 -p localhost:1666 info

User name: mbishop

Client name: mbishop-main
Client host: MichaelBook.local
Client root: /Users/mbishop/dev/perforce_1666/main
Current directory: /Users/mbishop/dev/perforce_1666/main
Client address: 127.0.0.1:49762
Server address: localhost:1666
Server root: /Users/mbishop/dev/PerforceDB
Server date: 2008/03/13 21:59:46 -0700 PDT
Server version: P4D/DARWIN80X86/2007.2/136993 (2007/10/18)
Server license: none

Putting it All Together

When using all of these flags together, it is possible to completely remove any
host:port combinations.

P4D

-0 -In "Main Development"

P4WEB

-p "Main Development" -0 -In "mbishop's" (Web-browser finds "mbishop's")

It is also possible to have a Perforce Server that doesn’t advertise, and a proxy and
p4web instance that do advertise.

P4D P4P
-p perforce:1666 -t perforce:1666 -0 -In "Proxy" (P4V finds "Proxy")

P4WEB

-p perforce:1666 -0 -In "mbishop's" (Web-browser finds "mbishop's")

Perforce and Zeroconf 8 Perforce Software ©2008

 Finally, it’s possible to have a Perforce Server that advertises on its local network and
a proxy which is connected to the server through a host:port which advertises on its
local network.

P4D
perforce

-0 -In "Hello" -p 1666 (P4V finds "Hello")

acme.com

P4P

-t perforce.acme.com:1666 -0 - (P4V finds "Hello2")

In "Hello2"

acme.co.uk

Perforce and Zeroconf 9 Perforce Software ©2008

4. Writing code to find Perforce services

ClientAPI Changes
There are no changes to the API. The P4PORT resolution is built-in to the Perforce
client libraries, so all clients will benefit.

Writing Browsing Code

Describing the actual API to browse for services is beyond the scope of this paper.
Luckily, there is an excellent reference from O’Reilly called Zero Configuration
Networking: The Definitive Guide.

Service types
In the world of Zeroconf, each service that can be browsed is identified by a “service
type”. In the conceptual diagrams in the overview, the web-server type was described
as “webserver”, but the actual service types are a little more obtuse. For example, if
you were to browse for web servers, the service type would be _http._tcp.
All standard service types can be found at an online registry, located at:
http://www.dns-sd.org/ServiceTypes.html

Perforce has registered _p4._tcp as the service-type for their protocol. If you write
code to browse for Perforce servers, you’ll need to specify this as the service type.
The P4Web advertisement conforms to the _http._tcp service type. If you browse for
_http._tcp, you’ll discover all the web-servers on your local network.

But what if you wanted to discover only P4Web instances? The Zeroconf standard
describes a way of specifying a “sub-type” of a service type using a comma-notation
(shown below). P4Web can advertise using a sub-type of “p4” so to specifically
browse for P4Web, use the subtype notation.

_http._tcp,p4

service-type sub-type

The subtype notation applies to p4ftpd as well.

Here is the table of Perforce service types:

Product Service Type

p4d _p4._tcp
p4p _p4._tcp
p4web _http._tcp,p4
p4ftpd _ftp._tcp,p4

Perforce and Zeroconf 10 Perforce Software ©2008

 TXT Records
When you resolve a service, you can inspect meta-data about the service before
connecting. The meta-data is in the form of key-value pairs stored in a DNS TXT
Record. When you browse, you will be given the list of key-value pairs. The Perforce
Server will export some standard TXT records with its products, as noted below.

Advertised TXT Records

Key p4d p4p p4web p4ftpd
description X X X X
version X X X X
target X X X
unicode X X

TXT Record Descriptions

description This is a description of the service. It will be in UTF-8.

version This is the version of the product. It will be in UTF-8.
Example: P4D/MACOSX104X86/2007.2/122958
target Available only with p4web and p4p . This is the P4PORT value of
that target.
For example, if a p4p instance were started with -t
perforce.acme.com:1666, the target TXT Record value would
contain perforce.acme.com:1666
unicode The presence of this TXT record is all that is needed to indicate
that the server is in Unicode mode.

Assumptions About P4PORT

P4PORT format
Before Zeroconf, P4PORT was always expected to have the format: host:port. With
Zeroconf, this will no longer be the case. Clients are encouraged to treat P4PORT as an
entire string that is the identifier of a Perforce server and not assume there is a colon
that separates two values.

Using P4PORT as a key

If you have data that you need to associate with a specific server, using P4PORT as a
key to identify that data is not recommended as many different P4PORT values can alias
to the same server.

Perforce and Zeroconf 11 Perforce Software ©2008

 Instead, read the ServerAddress: field from the p4 info command or, if you are using
p4 info -ztag, read the serverName field.

5. Ideas for the future

The Perforce Zeroconf implementation currently under development only uses
the .local domain for advertising. It is possible to support “wide-area” Zeroconf
browsing in the future but such work is currently only under investigation.
Please give us feedback and let us know what you would like to see!
[email protected]

Perforce and Zeroconf 12 Perforce Software ©2008

6. Appendices

Appendix A: Perforce service-types and TXT Records

Service Types

Product Service Type

p4d _p4._tcp
p4p _p4._tcp
p4web _http._tcp,p4
p4ftpd _ftp._tcp,p4

TXT Records

Key p4d p4p p4web p4ftpd example

description X X X X “This is my server”

version X X X X “P4D/MACOSX104X86/2007.2/122958”

target X X X “perforce.acme.com:1666”

“Test Server”

unicode X X <no value>

Appendix B: Useful Links and Documentation

Introductory Movie discussing Zeroconf
http://video.google.com/videoplay?docid=-7398680103951126462

Zero-Configuration Networking: The Definitive Guide

http://www.amazon.com/exec/obidos/redirect?path=ASIN/0596101007

Apple’s Bonjour Site

http://apple.com/bonjour

The registry of Zeroconf Service-Types

http://www.dns-sd.org/ServiceTypes.html

Perforce and Zeroconf 13 Perforce Software ©2008