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. A DC_SEC_QUERY (condor_ping) or a DC_AUTHENTICATE real command dispatches nothing: the server authorizes the command the client names as AuthCommand and answers for it.
• 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

• Constants
• func KeepOpen() error
• type Conn
  • func (c *Conn) AuthorizationLimits() []string
  • func (c *Conn) AuthorizationUser() string
  • func (c *Conn) InAuthorizationBoundingSet(perm string) bool
  • 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

Constants

const UnauthenticatedFQU = "unauthenticated@unmapped"

UnauthenticatedFQU is the identity HTCondor gives a peer that did not authenticate (UNAUTHENTICATED_FQU, src/condor_io/authentication.cpp). Sock::getFullyQualifiedUser (sock.cpp) returns it for an unauthenticated socket and DaemonCore passes that to IpVerify::Verify (daemon_command.cpp), so an ALLOW_* list admits such a peer only through an entry matching this string, e.g. "*" or "unauthenticated@unmapped". It is not "", which IpVerify::Verify treats as the wildcard user "*" (condor_ipverify.cpp).

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. Its User is the peer's authenticated identity, or "" when the
	// session did not authenticate (see AuthorizationUser).
	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) AuthorizationLimits

func (c *Conn) AuthorizationLimits() []string

AuthorizationLimits returns the authorization levels the peer's credential was limited to (e.g. by an IDTOKEN's "condor:/<LEVEL>" scopes), or nil if the session has no such bounding set (including raw commands). The server applies it to the command's registered levels before dispatch; a handler that authorizes at some other level itself should also check that level with InAuthorizationBoundingSet, as HTCondor daemons call Sock::isAuthorizationInBoundingSet.

func (*Conn) AuthorizationUser

func (c *Conn) AuthorizationUser() string

AuthorizationUser returns the identity to authorize this connection's peer as: its authenticated identity, or UnauthenticatedFQU when the peer did not authenticate (including raw commands). Handlers that consult an authorizer themselves should pass this rather than Negotiation.User.

func (*Conn) InAuthorizationBoundingSet

func (c *Conn) InAuthorizationBoundingSet(perm string) bool

InAuthorizationBoundingSet reports whether the session's authorization bounding set permits the level perm: always for ALLOW or a session with no bounding set, otherwise if perm is one of its levels or a level one of them implies (DAEMON implies WRITE and READ, ADVERTISE_STARTD implies READ, ...).

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

	// SecurityConfigForCommand, if set, selects a per-command security policy for
	// the handshake: once the client's requested command is known, the returned
	// config replaces SecurityConfig for that connection's negotiation. This lets
	// a daemon serve different commands at different HTCondor authorization levels
	// (e.g. a collector negotiating a QUERY at READ but an UPDATE at ADVERTISE).
	// Returning nil falls back to SecurityConfig. A returned config without its
	// own PostAuthPolicy or CommandPerms takes SecurityConfig's (installed by
	// New), so FQUMapper, the advertised ValidCommands and authorization limits
	// apply whatever the command's policy. Optional.
	SecurityConfigForCommand func(command int) *security.SecurityConfig

	// Authorizer, if set, reports whether a 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 of an
	// authenticated peer, or UnauthenticatedFQU for one that did not
	// authenticate, whatever identity its session records. 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. It also authorizes every
	// command before dispatch; on a full handshake that happens before the
	// handshake's reply, so a refused command is answered DENIED and its
	// session is not cached. 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). authUser is the
	// FQU the authentication method produced, as C++ HTCondor reports it before
	// any map file (e.g. condor@pool for an IDTOKENS peer, alice@$(UID_DOMAIN)
	// for FS). As with a C++ map file's result, a returned name without an '@'
	// takes SecurityConfig's UID domain (security.SecurityConfig.CanonicalUser).
	// Returning "" keeps the authenticated identity. Optional.
	FQUMapper func(authUser, peerAddr string) string

	// KeepAlive configures TCP keepalives applied to every connection accepted
	// in Serve. New() initializes it to stream.DefaultKeepAliveConfig
	// (SO_KEEPALIVE on; idle 360s, interval 5s, count 5), mirroring C++
	// HTCondor which enables keepalives on accepted daemon sockets so a
	// silently-dead peer (e.g. a powered-off execute host) is detected rather
	// than leaking a blocked handler goroutine. Set Enable=false to disable.
	KeepAlive stream.KeepAliveConfig
	// 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; a session whose credential limits its authorization levels may not run it.

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.