FreeBSD Manual Pages
WEMUX(1) WEMUX(1) NAME wemux - multi-user tmux sessions made easy SYNOPSIS Host or join multi-user tmux sessions. WEMUX HOST COMMANDS wemux start wemux attach wemux stop wemux users wemux kick wemux config wemux help WEMUX CLIENT COMMANDS: wemux mirror wemux pair wemux rogue wemux logout WEMUX SESSION COMMANDS: wemux join wemux reset wemux list DESCRIPTION wemux enhances tmux to make multi-user terminal multiplexing both easier and more powerful. It allows users to host a wemux session and have clients join in either: Mirror Mode gives clients (another SSH user on your machine) read-only ac- cess to the session, allowing them to see you work, or Pair Mode allows the client and yourself to work in the same terminal (shared cursor) or work independently in another window (separate cursors) in the same tmux session. It features multi-session support as well as user listing and notifications when users attach/detach. HOST COMMANDS wemux start Start a wemux session, chmod /tmp/wemux-wemux to 1777 so that other users may connect to it, and attach to it. If a wemux session already exists, it will attach to it instead. wemux attach Attach to an existing wemux session. wemux stop Kill the wemux session and remove the /tmp/wemux-wemux socket. wemux kick <var>username</var> Kick an SSH user from the server and remove their wemux pair sessions. wemux config Open /usr/local/etc/wemux/wemux.conf in your $EDITOR. wemux When wemux is run without any arguments in host mode, it is just like run- ning wemux start. It will reattach to an existing wemux session if it ex- ists, otherwise it will start a new session. CLIENT COMMANDS wemux mirror Attach to session in read-only mode. wemux pair Attach to session in pair mode, which allows editing. wemux rogue Attach to server in rogue mode, which allows editing and switching to win- dows independently from the host. wemux logout Remove your pair mode session. wemux When wemux is run without any arguments in client mode, its behavior at- tempts to intelligently select mirror, pair or rogue: * If the client does not have an existing rogue session it will attach to the wemux session in pair mode. * If the client has already started a wemux rogue mode session, it will reattach to the session in rogue mode. * By setting default_client_mode="rogue" in wemux.conf this can be changed to always join in pair mode, even if a pair session doesn't al- ready exist. Other Commands wemux passes commands it doesn't understand through to tmux with the cor- rect socket setting. wemux list-sessions is equivalent to entering tmux -S /tmp/wemux-wemux list-sessions USER LIST wemux can display a list of connected users, indicating users in mirror mode with [m] at the end of their name. If you'd like to see a list of all users currently connected to the wemux session, you have three options: wemux users Enter wemux users in the terminal to display a list of all currently con- nected wemux users. $ wemux users Users connected to 'wemux': 1. zolrath 2. csagan[m] Status Bar You can add the user list to your status bar by adding #(wemux sta- tus_users) where you see fit by editing your ~/tmux.conf file. set -g status-right "#(wemux status_users)" Display Message If you'd rather display users on command via a tmux message, similar to the user attachment/detachment messages, you can do so by editing your ~/tmux.conf file. Pick whatever key you'd like to bind the displaying the message to. Using t as an example: unbind t bind t run-shell 'wemux display_users' Note that the tmux prefix should be pressed before t to activate the com- mand. User listing can be disabled by setting allow_user_list="false" in we- mux.conf Short-form Commands All commands have a short form. s for start, a for attach, p for pair etc. For a complete list, type wemux help (or wemux h) MULTI-HOST MODE wemux supports specifying the joining different wemux sessions via wemux join <session>. This allows multiple hosts on the same machine to host their own independent wemux sessions with their own clients. By default this option is disabled. wemux will remember the last session specified to in order to make recon- necting to the same session easy. wemux help will output the currently specified session along with the wemux command list. Changing sessions can be enabled by setting allow_session_change="true" in /usr/local/etc/wemux/wemux.conf Joining Different wemux Sessions To change the wemux session run wemux join <session>. The name will be san- itized to contain no spaces or uppercase letters. $ wemux join Project X Changed wemux session from 'wemux' to 'project-x' $ wemux start $ wemux $ wemux stop $ wemux reset Changed wemux session from 'project-x' to 'wemux' wemux join <var>sessionname</var> Join wemux session with specified name. $ wemux join rails Changed wemux session from 'wemux' to 'rails' wemux join <var>sessionnumber</var> Alternatively, enter the session number displayed next to the session name in wemux list. $ wemux j 1 Changed wemux session from 'rails' to 'project-x' wemux join Join with no argument simply displays the current wemux server, if you're into that. $ wemux join Current wemux server: wemux Resetting the Session Name In order to easily return to the default session you can run wemux reset wemux reset Joins the default wemux session: wemux (or value of default_session_name in wemux.conf) $ wemux reset Changed wemux session from 'project-x' to 'wemux' Active Session List To list the name of all currently running wemux sessions run wemux list wemux list List all currently active wemux sessions. $ wemux list Currently active wemux sessions: 1. project-x 2. rails 3. wemux <- current session wemux join and wemux stop both accept either the name of a session or the number indicated next to the name in wemux list. Listing sessions can be disabled by setting allow_session_list="false" in /usr/local/etc/wemux/wemux.conf CONFIGURATION There are a number of additional options that be configured in /usr/lo- cal/etc/wemux/wemux.conf. In most cases the only option that must be changed is the host_list array. To open your wemux configuration file, you can either open /usr/local/etc/wemux/wemux.conf manually or run wemux con- fig An example configuration file is available at $(DOCDIR)/wemux.conf.ex- ample. Host Mode To have an account act as host, ensure that you have added their username to the /usr/local/etc/wemux/wemux.conf file's host_list array. host_list=(zolrath hostusername brocksamson) Pair Mode Pair mode can be disabled, only allowing clients to attach to the session in mirror mode by setting allow_pair_mode="false" Rogue Mode Rogue mode can be disabled, only allowing clients to attach to the server in mirror or pair mode by setting allow_rogue_mode="false" Default Client Mode When clients enter 'wemux' with no arguments by default it will first at- tempt to join an existing rogue mode session. If there is no rogue session it will start in pair mode. By setting default_client_mode to "rogue", 'we- mux' with no arguments will always join a rogue mode session, even if it has to create it. This can be changed by setting default_client_mode="rogue" Default Session Name The default wemux session name will be used with wemux reset and when al- low_session_change is not enabled in wemux.conf. This can be changed by setting default_session_name="customname" Changing Sessions The ability to change sessions can be enabled by setting allow_ses- sion_change="true" Listing Sessions Listing sessions can be disabled by setting allow_session_list="false" Listing Users Listing users can be disabled by setting allow_user_list="false" in we- mux.conf Kicking SSH Users Kicking SSH users from the server can be disabled by setting al- low_kick_user="false" in wemux.conf Announcements When a user joins a session in either mirror or pair mode, a message is displayed to all currently attached users: csagan has attached in mirror mode. csagan has detached. This can be disabled by setting announce_attach="false" In addition, when a user switches from one session to another via the wemux join <sessionname> command, their movement is displayed similarly to the attach messages. If csagan enters wemux join applepie the users on the default session wemux will see: csagan has switched to session: applepie If csagan returns to default session with: wemux reset users on wemux will see: csagan has joined this session. This can be disabled by setting announce_session_change="false" Automatic SSH Client Modes To make an SSHed user start in a wemux mode automatically, add one of the following lines to the users .bash_profile or .zshrc Option 1: Automatically log the client into mirror mode upon login, discon- nect them from the server when they detach. wemux mirror; exit Option 2: Automatically start the client in mirror mode but allow them to detach. wemux mirror Option 3: Automatically start the client in pair mode but allow them to de- tach. wemux pair Option 4: Only display the connection commands, don't automatically start any modes. wemux help Please note that this does not ensure a logged in user will not be able to exit tmux and access their shell. If the user is not trusted, you must per- form any security measures one would normally perform for a remote user. March 2014 WEMUX(1)
NAME | SYNOPSIS | DESCRIPTION | HOST COMMANDS | CLIENT COMMANDS | USER LIST | MULTI-HOST MODE | CONFIGURATION
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wemux&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>