1 files changed, 32 insertions, 11 deletions
diff --git a/usr.sbin/jexec/jexec.8 b/usr.sbin/jexec/jexec.8
index 40c4979..bdda23d 100644
--- a/usr.sbin/jexec/jexec.8
+++ b/usr.sbin/jexec/jexec.8
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 26, 2008
+.Dd November 29, 2008
 .Dt JEXEC 8
 .Os
 .Sh NAME
@@ -34,22 +34,36 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl u Ar username | Fl U Ar username
-.Op Fl h Ar hostname | Fl h Ar ip-number | Ar jid
-.Ar command ...
+.Op Fl n Ar jailname
+.Ar jid command ...
 .Sh DESCRIPTION
 The
 .Nm
 utility executes
 .Ar command
-inside the jail identified by
-.Ar hostname 
+inside the jail identified by either
+.Ar jailname
 or
-.Ar ip-number 
-or
-.Ar jid .
+.Ar jid
+or both.
+.Pp
+If the jail cannot be identified uniquely by the given parameters,
+an error message is printed.
+.Nm
+will also check the state of the jail (once supported) to be
+.Dv ALIVE
+and ignore jails in other states.
+The mandatory argument
+.Ar jid
+is the unique jail identifier as given by
+.Xr jls 8 .
+In case you only want to match on other criteria, give an empty string.
 .Pp
 The following options are available:
 .Bl -tag -width indent
+.It Fl n Ar jailname
+The name of the jail, if given upon creation of the jail.
+This is not the hostname of the jail.
 .It Fl u Ar username
 The user name from host environment as whom the
 .Ar command
@@ -59,9 +73,6 @@ The user name from jailed environment as whom the
 .Ar command
 should run.
 .El
-.Sh "CAUTIONS"
-Only jid is guaranteed to uniquely identify a jail.
-Hostname or ip-number only work here if matched to one unique jail.
 .Sh SEE ALSO
 .Xr jail_attach 2 ,
 .Xr jail 8 ,
@@ -71,3 +82,13 @@ The
 .Nm
 utility was added in
 .Fx 5.1 .
+.Sh BUGS
+If the jail is not identified by
+.Ar jid
+there is a possible race in between the lookup of the jail
+and executing the command inside the jail.
+Giving a
+.Ar jid
+has a similar race as another process can stop the jail and
+start another one after the user looked up the
+.Ar jid .