Hands-Free Server Discovery: Perforce and Zero ......Hands-Free Server Discovery: Perforce and...

Hands-Free Server Discovery:

Perforce and Zero-

Configuration NetworkingMichael Bishop, Perforce Software

Perforce and Zeroconf 1 Perforce Software ©2008

This paper refers to functionality

that is still under development

and is not supported as of the

2008.1 Perforce Server release.

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


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.

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

DNS

I've got a webserver

listening on port 8080

called "Personal Web"

pub.acme.com

acme.com


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.

DNS




pub.acme.com

acme.com

Do you know any

webservers?

goof.acme.com

I know one at pub.acme.com:8080


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

PowerBook G4

= the daemon

DNS

.local

pub.local

(also pub.acme.com)

goof.local

(also goof.acme.com)

papasmurf.local

(no other address)


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

DNS




pub.local

.local

Do you know any

webservers?

goof.local

I know one at pub.local:8080


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

Advertising Meta-dataAdvertisements 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”.

DNS

I've got a printer listening on port 478

called "Gutenberg"location="Next to the Kitchen"

gutenberg.local.local

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

its advertisements.


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


Browsing for Perforce ServersStarting 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

-Id

"Main Development"

"Development only. Check your

core dumps into the debugging

server"

P4D

"Perforce 日本"

Main Development Development only. Check your core dumps in

Perforce 日本メーン・デバ・サーバー

Sample GUI BrowserServers

-0

-In

-Id "メーン・デバ・サーバー"

The New P4PORTThe 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: mbishopClient name: mbishop-mainClient host: MichaelBook.localClient root: /Users/mbishop/dev/perforce_1666/mainCurrent directory: /Users/mbishop/dev/perforce_1666/mainClient address: 127.0.0.1:49762Server address: localhost:1666Server root: /Users/mbishop/dev/PerforceDBServer date: 2008/03/13 21:59:46 -0700 PDTServer version: P4D/DARWIN80X86/2007.2/136993 (2007/10/18)Server license: none


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

combination.

Example

> p4 -p localhost:1666 info

User name: mbishopClient name: mbishop-mainClient host: MichaelBook.localClient root: /Users/mbishop/dev/perforce_1666/mainCurrent directory: /Users/mbishop/dev/perforce_1666/mainClient address: 127.0.0.1:49762Server address: localhost:1666Server root: /Users/mbishop/dev/PerforceDBServer date: 2008/03/13 21:59:46 -0700 PDTServer version: P4D/DARWIN80X86/2007.2/136993 (2007/10/18)Server license: none

Putting it All TogetherWhen 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

-p perforce:1666

P4WEB

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

P4P

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


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

-0 -In "Hello" -p 1666

P4P

-t perforce.acme.com:1666 -0 -In "Hello2"

(P4V finds "Hello2")

perforce

(P4V finds "Hello")

acme.com

acme.co.uk


4. Writing code to find Perforce services

ClientAPI ChangesThere are no changes to the API. The P4PORT resolution is built-in to the Perforce

client libraries, so all clients will benefit.

Writing Browsing CodeDescribing 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




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.


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]


mailto:[email protected]

mailto:[email protected]

6. Appendices

Appendix A: Perforce service-types and TXT RecordsService 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 DocumentationIntroductory 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









Date post:	31-Dec-2020
Category:	Documents
Upload:	others
View:	12 times
Download:	0 times

Hands-Free Server Discovery: Perforce and Zero ......Hands-Free Server Discovery: Perforce and...

Documents