git: 1595a4087b19 - stable/13 - jexec.8: Add examples section

From: Danilo G. Baio <dbaio_at_FreeBSD.org>
Date: Tue, 10 Oct 2023 23:20:14 UTC
The branch stable/13 has been updated by dbaio:

URL: https://cgit.FreeBSD.org/src/commit/?id=1595a4087b1947974b2f3fa18e31f79ab6a56572

commit 1595a4087b1947974b2f3fa18e31f79ab6a56572
Author:     Danilo G. Baio <dbaio@FreeBSD.org>
AuthorDate: 2023-10-07 22:44:44 +0000
Commit:     Danilo G. Baio <dbaio@FreeBSD.org>
CommitDate: 2023-10-10 23:18:58 +0000

    jexec.8: Add examples section
    
    MFC after:      3 days
    Reviewed by:    gbe, 0mp, danfe, pauamma_gundo.com
    Differential Revision: https://reviews.freebsd.org/D40831
    
    (cherry picked from commit 04c8bfc1761010c36081cf300fa751548d541122)
---
 usr.sbin/jexec/jexec.8 | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/usr.sbin/jexec/jexec.8 b/usr.sbin/jexec/jexec.8
index 69f380676c30..4400cbbe56a3 100644
--- a/usr.sbin/jexec/jexec.8
+++ b/usr.sbin/jexec/jexec.8
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd April 24, 2016
+.Dd October 7, 2023
 .Dt JEXEC 8
 .Os
 .Sh NAME
@@ -65,6 +65,44 @@ The user name from jailed environment as whom the
 .Ar command
 should run.
 .El
+.Sh EXAMPLES
+.Ss Example 1 : Open a shell in a jail
+The following command specifies a jail by its name and utilizes the current
+user's shell:
+.Pp
+.Dl # jexec name
+.Pp
+It is also possible to specify a jail by its jid:
+.Pp
+.Dl # jexec JID
+.Ss Example 2 : Run a single command without opening a shell
+The following command runs
+.Ql uname -a
+in a jail called
+.Dq name .
+Since a command is specified explicitly,
+.Nm
+does not spawn an interactive shell.
+Instead,
+.Nm
+executes the specified command directly.
+.Pp
+.Dl # jexec name uname -a
+.Ss Example 3 : Open a shell in a jail with a clean environment
+The following command opens a
+.Xr sh 1
+shell in a jail with a clean environment:
+.Pp
+.Dl # jexec -l name sh
+.Ss Example 4 : Open a shell in a jail with the login command
+The following command utilizes
+.Xr login 1
+to access the jail, submitting an audit record, and displaying the
+user's last login, system copyright, and
+.Xr motd 5
+message:
+.Pp
+.Dl # jexec -l name login -f root
 .Sh SEE ALSO
 .Xr jail_attach 2 ,
 .Xr jail 8 ,