.\" $OpenBSD: pledge.2,v 1.83 2026/04/01 02:34:37 jsg Exp $
.\"
.\" Copyright (c) 2015 Nicholas Marriott <nicm@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 1 2026 $
.Dt PLEDGE 2
.Os
.Sh NAME
.Nm pledge
.Nd restrict system operations
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn pledge "const char *promises" "const char *execpromises"
.Sh DESCRIPTION
The
.Fn pledge
system call separates the POSIX feature set into a group of approximately
3 dozen subsystems.
By calling
.Fn pledge
the program can declare which subsystems it will need in the
future in a space-separated string called
.Ar promises .
Subsystems not listed become unavailable, and most attempts to use operations
in that subsystem result in the process being killed with an uncatchable
.Dv SIGABRT ,
delivering a core file if possible.
.Pp
Subsequent calls to
.Fn pledge
can reduce the subsystems which still work, but previously
revoked subsystems cannot be re-activated.
.Pp
Passing
.Dv NULL
to
.Fa promises
or
.Fa execpromises
specifies to not change the current value.
.Pp
A few changes to POSIX behaviour come into effect on the first call to
.Fn pledge ,
regardless of the
.Va promise
arguments:
.Bl -ohang -offset indent
.It Xr adjtime 2 :
Time cannot be changed.
Only the
.Va olddelta
argument works.
.It Xo
.Xr chmod 2 ,
.Xr fchmod 2 ,
.Xr fchmodat 2 ,
.Xr chown 2 ,
.Xr lchown 2 ,
.Xr fchown 2 ,
.Xr fchownat 2 ,
.Xr mkfifo 2 ,
and
.Xr mknod 2 :
.Xc
Setuid/setgid/sticky bits are ignored.
User or group cannot be changed.
The
.Cm fattr
promise
relaxes this behaviour slightly.
.It Xr ioctl 2 :
Only the
.Dv FIONREAD ,
.Dv FIONBIO ,
.Dv FIOCLEX ,
and
.Dv FIONCLEX
operations are allowed by default.
All other ioctl operations are blocked, except for ones which are enabled
by specific
.Va promises :
.Cm audio ,
.Cm bpf ,
.Cm disklabel ,
.Cm drm ,
.Cm inet ,
.Cm pf ,
.Cm route ,
.Cm wroute ,
.Cm tape ,
.Cm tty ,
.Cm video ,
and
.Cm vmm .
.It Xo
.Xr mmap 2
and
.Xr mprotect 2 :
.Xc
.Dv PROT_EXEC
is not allowed, unless the
.Cm prot_exec
.Va promise
is requested.
.It Xr __pledge_open 2 :
A few system files can be opened directly by
.Li libc
internal code using this hidden symbol system call when
specific
.Fa promises
are requested, but applications cannot open those files themselves.
This works even when
.Cm rpath
or
.Cm wpath
are absent and
.Xr unveil 2
cannot block opening the files.
These are the promises which can read special files:
.Va promises .
.Bl -tag -width "prot_exec" -offset indent
.It Cm stdio
.Pa /etc/localtime
.br
.Pa /usr/share/zoneinfo
(and files below)
.br
.Pa /dev/null
(for read and/or write)
.It Cm tty
.Pa /dev/tty
(for read and/or write)
.It Cm getpw
.Pa /etc/spwd.db
(refused with EPERM)
.br
.Pa /etc/pwd.db
.Pa /etc/group
.Pa /etc/netid
.It Cm dns
.Pa /etc/resolv.conf
.Pa /etc/hosts
.Pa /etc/services
.Pa /etc/protocols
.El
.It Fn pledge :
Can only reduce permissions for
.Fa promises
and
.Fa execpromises .
.It Xr sysctl 2 :
A small set of read-only operations are allowed, sufficient to
support:
.Xr getdomainname 3 ,
.Xr gethostname 3 ,
.Xr getifaddrs 3 ,
.Xr uname 3 ,
and system sensor readings.
Some
.Va promises
expose more read-only operations.
.El
.Pp
The
.Fa promises
argument is specified as a string, with space separated keywords.
Using
.Qq \&
restricts the process to the
.Xr _exit 2
system call
(this can be used for pure computation operating on memory shared
with another process).
.Bl -tag -width "prot_exec" -offset indent
.It Cm stdio
This
.Va promise
provides access to basic memory management, actions upon already
open file descriptors, inspection of various process attributes,
timer resources, and other subsystems generally considered safe because
they only occur inside the process..
Many of these interfaces are then used inside higher-level libc
functionality, which is why the name
.Cm stdio
was chosen.
The following system calls are permitted:
.Pp
.Xr clock_getres 2 ,
.Xr clock_gettime 2 ,
.Xr close 2 ,
.Xr closefrom 2 ,
.Xr dup 2 ,
.Xr dup2 2 ,
.Xr dup3 2 ,
.Xr fchdir 2 ,
.Xr fcntl 2 ,
.Xr fstat 2 ,
.Xr fsync 2 ,
.Xr ftruncate 2 ,
.Xr getdtablecount 2 ,
.Xr getegid 2 ,
.Xr getentropy 2 ,
.Xr geteuid 2 ,
.Xr getgid 2 ,
.Xr getgroups 2 ,
.Xr getitimer 2 ,
.Xr getlogin 2 ,
.Xr getpgid 2 ,
.Xr getpgrp 2 ,
.Xr getpid 2 ,
.Xr getppid 2 ,
.Xr getresgid 2 ,
.Xr getresuid 2 ,
.Xr getrlimit 2 ,
.Xr getrtable 2 ,
.Xr getsid 2 ,
.Xr getthrid 2 ,
.Xr gettimeofday 2 ,
.Xr getuid 2 ,
.Xr issetugid 2 ,
.Xr kevent 2 ,
.Xr kqueue 2 ,
.Xr kqueue1 2 ,
.Xr lseek 2 ,
.Xr madvise 2 ,
.Xr minherit 2 ,
.Xr mmap 2 ,
.Xr mprotect 2 ,
.Xr mquery 2 ,
.Xr munmap 2 ,
.Xr nanosleep 2 ,
.Xr pipe 2 ,
.Xr pipe2 2 ,
.Xr poll 2 ,
.Xr pread 2 ,
.Xr preadv 2 ,
.Xr profil 2 ,
.Xr pwrite 2 ,
.Xr pwritev 2 ,
.Xr read 2 ,
.Xr readv 2 ,
.Xr recvfrom 2 ,
.Xr recvmsg 2 ,
.Xr select 2 ,
.Xr sendmsg 2 ,
.Xr sendsyslog 2 ,
.Xr sendto 2 ,
.Xr setitimer 2 ,
.Xr shutdown 2 ,
.Xr sigaction 2 ,
.Xr sigprocmask 2 ,
.Xr sigreturn 2 ,
.Xr socketpair 2 ,
.Xr umask 2 ,
.Xr wait4 2 ,
.Xr waitid 2 ,
.Xr write 2 ,
.Xr writev 2
.Pp
.Xr sendto 2
is only permitted if the destination socket address is
.Dv NULL .
.It Cm rpath
A number of system calls are allowed which allow path traversal,
reading
.Vt struct stat ,
and opening files for read.
.It Cm wpath
Similar to
.Cm rpath ,
but files can be opened for write.
.It Cm cpath
Similar to
.Cm wpath ,
but files can also be created or removed.
.It Cm dpath
Similar to
.Cm cpath ,
but special files can be created using:
.Pp
.Xr mkfifo 2 ,
.Xr mknod 2
.It Cm tmppath
No longer available.
This pledge was designed to satisfy the
.Xr mkstemp 3
family of functions.
The limited filesystem access it provided is now disabled, so the
promise has been removed and will
return
.Er EINVAL .
It should be replaced by either
allowing use of the whole filesystem, meaning
.Qq rpath wpath cpath ,
or use of
.Xr unveil 2
with
.Fa path
.Qq /tmp
and
.Fa permissions
.Qq rwc .
.It Cm inet
The following system calls are allowed to operate in the
.Dv AF_INET
and
.Dv AF_INET6
domains
(though
.Xr setsockopt 2
has been substantially reduced in functionality):
.Pp
.Xr socket 2 ,
.Xr listen 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr accept4 2 ,
.Xr accept 2 ,
.Xr getpeername 2 ,
.Xr getsockname 2 ,
.Xr setsockopt 2 ,
.Xr getsockopt 2
.It Cm mcast
In combination with
.Cm inet
give back functionality to
.Xr setsockopt 2
for operating on multicast sockets.
.It Cm fattr
The following system calls are allowed to make explicit changes
to fields in
.Vt struct stat
relating to a file:
.Pp
.Xr utimes 2 ,
.Xr futimes 2 ,
.Xr utimensat 2 ,
.Xr futimens 2 ,
.Xr chmod 2 ,
.Xr fchmod 2 ,
.Xr fchmodat 2 ,
.Xr chflags 2 ,
.Xr chflagsat 2 ,
.Xr chown 2 ,
.Xr fchownat 2 ,
.Xr lchown 2 ,
.Xr fchown 2 ,
.Xr utimes 2
.It Cm chown
The
.Xr chown 2
family is allowed to change the user or group on a file.
.It Cm flock
File locking via
.Xr fcntl 2 ,
.Xr flock 2 ,
.Xr lockf 3 ,
and
.Xr open 2
is allowed.
No distinction is made between shared and exclusive locks.
This promise is required for unlock as well as lock.
.It Cm unix
The following system calls are allowed to operate in the
.Dv AF_UNIX
domain:
.Pp
.Xr socket 2 ,
.Xr listen 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr accept4 2 ,
.Xr accept 2 ,
.Xr getpeername 2 ,
.Xr getsockname 2 ,
.Xr setsockopt 2 ,
.Xr getsockopt 2
.Pp
The
.Xr bind 2
call can create AF_UNIX sockets at any path even without
.Cm wpath ,
and
.Xr connect 2
can connect at any path
even without
.Cm rpath
or
.Cm wpath .
.It Cm dns
Some low-level behaviours required by the DNS resolver described in
.Xr res_init 3
are permitted.
This includes
.Xr __pledge_open 2
reading
.Xr hosts 5 ,
.Xr protocols 5 ,
.Xr resolv.conf 5 ,
and
.Xr services 5 ,
and exposing a few networking system calls:
.Xr socket 2 ,
.Xr connect 2 ,
.Xr sendto 2 ,
.Xr recvfrom 2
which can only operate on the specific socket type
.Dv SOCK_DNS .
The library resolver opens sockets with
.Dv SOCK_DNS
only on port 53, so the kernel can differentiate these operations
from regular sockets operations.
.It Cm getpw
This uses the special features of
.Xr __pledge_open 2
to read required system files to support the
.Xr getpwnam 3 ,
.Xr getgrnam 3 ,
.Xr getgrouplist 3 ,
and
.Xr initgroups 3
family of functions, including lookups via the
.Xr yp 8
protocol for YP and LDAP databases.
.It Cm sendfd
Allows sending of file descriptors using
.Xr sendmsg 2 .
File descriptors referring to directories may not be passed.
.It Cm recvfd
Allows receiving of file descriptors using
.Xr recvmsg 2 .
File descriptors referring to directories may not be passed.
.It Cm tape
Allow
.Dv MTIOCGET
and
.Dv MTIOCTOP
operations against tape drives.
.It Cm tty
In addition to allowing read-write operations on
.Pa /dev/tty ,
this opens up a variety of
.Xr ioctl 2
requests used by tty devices.
If
.Cm tty
is accompanied with
.Cm rpath ,
.Xr revoke 2
is permitted.
Otherwise only the following
.Xr ioctl 2
requests are permitted:
.Pp
.Dv TIOCSPGRP ,
.Dv TIOCGETA ,
.Dv TIOCGPGRP ,
.Dv TIOCGWINSZ ,
.Dv TIOCSWINSZ ,
.Dv TIOCSBRK ,
.Dv TIOCCDTR ,
.Dv TIOCSETA ,
.Dv TIOCSETAW ,
.Dv TIOCSETAF ,
.Dv TIOCUCNTL
.It Cm proc
Allows the following process relationship operations:
.Pp
.Xr fork 2 ,
.Xr vfork 2 ,
.Xr kill 2 ,
.Xr getpriority 2 ,
.Xr setpriority 2 ,
.Xr setrlimit 2 ,
.Xr setpgid 2 ,
.Xr setsid 2
.It Cm exec
Allows a process to call
.Xr execve 2 .
Coupled with the
.Cm proc
promise, this allows a process to fork and execute another program.
If
.Fa execpromises
has been previously set the new program begins with those promises,
unless setuid/setgid bits are set in which case execution is blocked with
.Er EACCES .
Otherwise the new program starts running without pledge active,
and hopefully makes a new pledge soon.
.It Cm prot_exec
Allows the use of
.Dv PROT_EXEC
with
.Xr mmap 2
and
.Xr mprotect 2 .
.It Cm settime
Allows the setting of system time, via the
.Xr settimeofday 2 ,
.Xr adjtime 2 ,
and
.Xr adjfreq 2
system calls.
.It Cm ps
Allows enough
.Xr sysctl 2
interfaces to allow inspection of processes operating on the system using
programs like
.Xr ps 1 .
.It Cm vminfo
Allows enough
.Xr sysctl 2
interfaces to allow inspection of the system's virtual memory by
programs like
.Xr top 1
and
.Xr vmstat 8 .
.It Cm id
Allows the following system calls which can change the rights of a
process:
.Pp
.Xr setuid 2 ,
.Xr seteuid 2 ,
.Xr setreuid 2 ,
.Xr setresuid 2 ,
.Xr setgid 2 ,
.Xr setegid 2 ,
.Xr setregid 2 ,
.Xr setresgid 2 ,
.Xr setgroups 2 ,
.Xr setlogin 2 ,
.Xr setrlimit 2 ,
.Xr getpriority 2 ,
.Xr setpriority 2 ,
.Xr setrtable 2
.It Cm pf
Allows a subset of
.Xr ioctl 2
operations on the
.Xr pf 4
device:
.Pp
.Dv DIOCADDRULE ,
.Dv DIOCGETSTATUS ,
.Dv DIOCNATLOOK ,
.Dv DIOCRADDTABLES ,
.Dv DIOCRCLRADDRS ,
.Dv DIOCRCLRTABLES ,
.Dv DIOCRCLRTSTATS ,
.Dv DIOCRGETTSTATS ,
.Dv DIOCRSETADDRS ,
.Dv DIOCXBEGIN ,
.Dv DIOCXCOMMIT
.It Cm route
Allow inspection of the routing table.
.It Cm wroute
Allow changes to the routing table.
.It Cm audio
Allows a subset of
.Xr ioctl 2
operations on
.Xr audio 4
devices
(see
.Xr sio_open 3
for more information):
.Pp
.Dv AUDIO_GETPOS ,
.Dv AUDIO_GETPAR ,
.Dv AUDIO_SETPAR ,
.Dv AUDIO_START ,
.Dv AUDIO_STOP ,
.Dv AUDIO_MIXER_DEVINFO ,
.Dv AUDIO_MIXER_READ ,
.Dv AUDIO_MIXER_WRITE
.It Cm video
Allows a subset of
.Xr ioctl 2
operations on
.Xr video 4
devices:
.Pp
.Dv VIDIOC_DQBUF ,
.Dv VIDIOC_ENUM_FMT ,
.Dv VIDIOC_ENUM_FRAMEINTERVALS ,
.Dv VIDIOC_ENUM_FRAMESIZES ,
.Dv VIDIOC_G_CTRL ,
.Dv VIDIOC_G_PARM ,
.Dv VIDIOC_QBUF ,
.Dv VIDIOC_QUERYBUF ,
.Dv VIDIOC_QUERYCAP ,
.Dv VIDIOC_QUERYCTRL ,
.Dv VIDIOC_S_CTRL ,
.Dv VIDIOC_S_FMT ,
.Dv VIDIOC_S_PARM ,
.Dv VIDIOC_STREAMOFF ,
.Dv VIDIOC_STREAMON ,
.Dv VIDIOC_TRY_FMT ,
.Dv VIDIOC_REQBUFS
.It Cm bpf
Allow
.Dv BIOCGSTATS
operation for statistics collection from a
.Xr bpf 4
device.
.It Cm unveil
Allow
.Xr unveil 2
to be called.
.It Cm error
Rather than killing the process upon violation, indicate error with
.Er ENOSYS .
.Pp
Also when
.Fn pledge
is called with higher
.Fa promises
or
.Fa execpromises ,
those changes will be ignored and return success.
This is useful when a parent enforces
.Fa execpromises
but an execve'd child has a different idea.
.El
.Pp
A process currently running with pledge has state
.Sq p
in
.Xr ps 1
output; a process that was terminated due to a pledge violation
is accounted by
.Xr lastcomm 1
with the
.Sq P
flag.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
.Fn pledge
will fail if:
.Bl -tag -width Er
.It Bq Er EFAULT
.Fa promises
or
.Fa execpromises
points outside the process's allocated address space.
.It Bq Er EINVAL
.Fa promises
is malformed or contains invalid keywords.
.It Bq Er EPERM
This process is attempting to increase permissions.
.El
.Sh HISTORY
The
.Fn pledge
system call first appeared in
.Ox 5.9 .