server

Documentation

Overview

Package server provides reusable scaffolding for building CEDAR command servers (daemons that accept connections, authenticate, and dispatch HTCondor commands). It complements the client-focused packages in this module.

Two kinds of command handlers are supported:

• Authenticated commands: the client opens the exchange with a DC_AUTHENTICATE command and a security ClassAd that carries the real command (e.g. CCB_REGISTER). The server performs the security handshake and dispatches on the real command.
• Raw commands: the client sends a bare command integer with no security handshake (e.g. CCB_REVERSE_CONNECT, which HTCondor registers as ALLOW and sends via the "raw" command protocol). These are dispatched directly with no authentication.

Index

• func KeepOpen() error
• type Conn
  • func (c *Conn) KeepAlive()
  • func (c *Conn) PeerVersion() string
• type HandlerFunc
• type Server
  • func New(secConfig *security.SecurityConfig) *Server
  • func (s *Server) CommandPerms(command int) []string
  • func (s *Server) Handle(command int, fn HandlerFunc, perms ...string)
  • func (s *Server) HandleRaw(command int, fn HandlerFunc)
  • func (s *Server) Serve(ctx context.Context, l net.Listener) error
  • func (s *Server) ServeConn(ctx context.Context, conn net.Conn) error

Functions

func KeepOpen

func KeepOpen() error

KeepOpen is returned by a handler that has taken ownership of the connection (e.g. a persistent CCB registration socket or a proxied stream). ServeConn will not close the underlying connection in that case.

Types

type Conn

type Conn struct {
	// Stream is the CEDAR stream for the connection. For authenticated
	// commands it is authenticated (and possibly encrypted) by the time the
	// handler runs; for raw commands it is plaintext.
	Stream *stream.Stream

	// Command is the real HTCondor command being dispatched.
	Command int

	// Negotiation is the result of the security handshake, or nil for raw
	// commands.
	Negotiation *security.SecurityNegotiation

	// Message is the inbound Message the leading command integer was read
	// from. Raw-command handlers read their payload (e.g. a ClassAd) from
	// this message; authenticated handlers normally start a fresh message.
	// For a follow-on command on a kept-alive connection (see KeepAlive) it is
	// the message the follow-on command integer was read from, so the handler
	// reads that command's ad from the same message.
	Message *message.Message

	// RemoteAddr is the peer's network address.
	RemoteAddr string
	// contains filtered or unexported fields
}

Conn is the per-connection context handed to a command handler.

func (*Conn) KeepAlive

func (c *Conn) KeepAlive()

KeepAlive requests that, after this handler returns nil, the server keep the connection open and dispatch the next command the peer sends on the same session (rather than closing). Used by update handlers to serve HTCondor's persistent command-socket protocol. Ignored if the handler returns an error.

func (*Conn) PeerVersion

func (c *Conn) PeerVersion() string

PeerVersion returns the peer's reported $CondorVersion$ string, or "" if it was not exchanged (e.g. for raw commands).

type HandlerFunc

type HandlerFunc func(ctx context.Context, c *Conn) error

HandlerFunc handles a single dispatched command. Returning an error closes the connection unless the handler has taken ownership of it (see KeepOpen).

type Server

type Server struct {
	// SecurityConfig is used for the server side of the security handshake on
	// authenticated commands. It must be non-nil if any authenticated handler
	// is registered.
	SecurityConfig *security.SecurityConfig

	// Authorizer, if set, reports whether an authenticated peer is allowed at a
	// given authorization level. perm is an HTCondor DCpermission name (e.g.
	// "READ", "DAEMON"); peerAddr is the peer's "host:port"; user is the mapped
	// FQU. The server consults it — for every registered authenticated command's
	// levels — to compute the session's ValidCommands after authentication, so a
	// peer can reuse the session for any command it is authorized for. Leaving it
	// nil advertises only the negotiated command (no authorization table applied).
	Authorizer func(perm, peerAddr, user string) bool

	// FQUMapper, if set, maps an authenticated identity to the fully-qualified
	// user to advertise and authorize as (e.g. via a mapfile). Returning "" keeps
	// the authenticated identity. Optional.
	FQUMapper func(authUser, peerAddr string) string
	// contains filtered or unexported fields
}

Server accepts CEDAR connections and dispatches commands to handlers.

func New

func New(secConfig *security.SecurityConfig) *Server

New creates a Server with the given server-side security configuration. It installs the server's ValidCommands computation as the security layer's post-auth policy, so authenticating peers learn every command they are authorized for (see Authorizer).

func (*Server) CommandPerms

func (s *Server) CommandPerms(command int) []string

CommandPerms returns the authorization levels registered for command, or nil if it is unregistered or raw. Callers enforcing per-command authorization should verify a peer against these levels so their decision matches the ValidCommands the server advertises.

func (*Server) Handle

func (s *Server) Handle(command int, fn HandlerFunc, perms ...string)

Handle registers an authenticated handler for a command. The optional perms are the authorization levels (HTCondor DCpermission names, e.g. "READ" or "DAEMON") that authorize the command; a peer is authorized if it satisfies any one of them. The levels drive both the ValidCommands the server advertises after authentication and, for callers that enforce it, per-command authorization (see CommandPerms). Registering with no perms advertises the command only as the negotiated one and applies no authorization table.

func (*Server) HandleRaw

func (s *Server) HandleRaw(command int, fn HandlerFunc)

HandleRaw registers a handler for a raw (un-authenticated) command. The command integer arrives with no preceding DC_AUTHENTICATE.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context, l net.Listener) error

Serve accepts connections from l until the context is cancelled or Accept fails permanently. Each connection is handled in its own goroutine.

func (*Server) ServeConn

func (s *Server) ServeConn(ctx context.Context, conn net.Conn) error

ServeConn handles a single already-accepted connection: it reads the leading command integer, performs the security handshake for authenticated commands, and dispatches to the registered handler.