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 access 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.conf in your $EDITOR.

  wemux
When wemux is run without any arguments in host mode, it is just like running wemux start. It will reattach to an existing wemux session if it exists, 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 windows independently from the host.

  wemux logout
Remove your pair mode session.

  wemux
When wemux is run without any arguments in client mode, its behavior attempts 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 already exist.

  Other Commands
wemux passes commands it doesn't understand through to tmux with the correct 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 connected 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 status_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 command.

User listing can be disabled by setting allow_user_list="false" in wemux.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 reconnecting 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.conf

  Joining Different wemux Sessions
To change the wemux session run wemux join <session>. The name will be sanitized 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.conf

CONFIGURATION
There are a number of additional options that be configured in /usr/local/etc/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.conf manually or run wemux config

  Host Mode
To have an account act as host, ensure that you have added their username to the /usr/local/etc/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 attempt 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", 'wemux' 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 allow_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_session_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 wemux.conf

  Kicking SSH Users
Kicking SSH users from the server can be disabled by setting allow_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, disconnect 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 detach.
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 perform any security measures one would normally perform for a remote user.