1.\" Copyright (c) 2026 Baptiste Daroussin <bapt@FreeBSD.org> 2.\" 3.\" SPDX-License-Identifier: BSD-2-Clause 4.\" 5.Dd March 17, 2026 6.Dt PKG-SERVE 8 7.Os 8.Sh NAME 9.Nm pkg-serve 10.Nd serve pkg repositories over TCP via inetd 11.Sh SYNOPSIS 12.Nm 13.Ar basedir 14.Sh DESCRIPTION 15The 16.Nm 17utility serves 18.Xr pkg 8 19repositories using the pkg TCP protocol. 20It is designed to be invoked by 21.Xr inetd 8 22and communicates via standard input and output. 23.Pp 24The 25.Ar basedir 26argument specifies the root directory containing the package repositories. 27All file requests are resolved relative to this directory. 28.Pp 29On startup, 30.Nm 31enters a Capsicum sandbox, restricting filesystem access to 32.Ar basedir . 33.Sh PROTOCOL 34The protocol is line-oriented. 35Upon connection, the server sends a greeting: 36.Bd -literal -offset indent 37ok: pkg-serve <version> 38.Ed 39.Pp 40The client may then issue commands: 41.Bl -tag -width "get file age" 42.It Ic get Ar file age 43Request a file. 44If the file's modification time is newer than 45.Ar age 46(a Unix timestamp), the server responds with: 47.Bd -literal -offset indent 48ok: <size> 49.Ed 50.Pp 51followed by 52.Ar size 53bytes of file data. 54If the file has not been modified, the server responds with: 55.Bd -literal -offset indent 56ok: 0 57.Ed 58.Pp 59On error, the server responds with: 60.Bd -literal -offset indent 61ko: <error message> 62.Ed 63.It Ic quit 64Close the connection. 65.El 66.Sh INETD CONFIGURATION 67Add the following line to 68.Xr inetd.conf 5 : 69.Bd -literal -offset indent 70pkg stream tcp nowait nobody /usr/libexec/pkg-serve pkg-serve /usr/local/poudriere/data/packages 71.Ed 72.Pp 73And define the service in 74.Xr services 5 : 75.Bd -literal -offset indent 76pkg 62000/tcp 77.Ed 78.Sh REPOSITORY CONFIGURATION 79On the client side, configure a repository in 80.Pa /usr/local/etc/pkg/repos/myrepo.conf 81to use the 82.Ic tcp:// 83scheme: 84.Bd -literal -offset indent 85myrepo: { 86 url: "tcp://pkgserver.example.com:62000/myrepo", 87} 88.Ed 89.Pp 90The path component of the URL is resolved relative to the 91.Ar basedir 92given to 93.Nm . 94For example, if 95.Nm 96is started with 97.Pa /usr/local/poudriere/data/packages 98as 99.Ar basedir , 100the above configuration will serve files from 101.Pa /usr/local/poudriere/data/packages/myrepo/ . 102.Sh SEE ALSO 103.Xr inetd 8 , 104.Xr inetd.conf 5 , 105.Xr pkg 8 106.Sh AUTHORS 107.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org 108