{
    "info": {
        "author": "Benjamin Le Forestier",
        "author_email": "benjamin@leforestier.org",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Developers",
            "Intended Audience :: System Administrators",
            "License :: OSI Approved :: BSD License",
            "Operating System :: POSIX :: BSD :: FreeBSD",
            "Programming Language :: Python",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Topic :: System :: Operating System",
            "Topic :: System :: Systems Administration"
        ],
        "description": "-----\nmjail\n-----\n\n*mjail* is a command line tool to create and manage jails on FreeBSD.\n\nWith *mjail*, you can create a jail in a single command and have a virtual machine ready to work with.\n\nFor example, you can use *mjail* to create multiple independant ssh boxes on your remote server, and then be able to access them from your laptop, in the same way you'd access any Unix host, using ssh and a private key.\n\n*mjail* integrates with the *pf* firewall to allow quick management of port redirections to the jails.\n\n*mjail* relies on ``jail.conf`` and so is compatible with the newest versions of FreeBSD.\n\n--------\nFeatures\n--------\n\nEach of these features can be achieved by issuing a single `mjail` command.\n\n- create a jail with an ip address on a virtual interface of the host\n- create a jail that is accessible from the internet via ssh and a private key\n- start/stop a jail\n- delete a jail\n- start a shell inside a jail\n- update the base system of a jail\n- redirect any internet facing port of the host to a port of a jail\n\n-------------\nInstallation\n-------------\n\nYou need to have the *pf* firewall and the *local_unbound* local DNS server enabled. Two simple commands will ensure this is the case. Run, as root:\n\n\n.. code::\n\n    sysrc pf_enable=YES\n    sysrc local_unbound_enable=YES\n\n(the mjail initialization described in the next section will start these services if they aren't already running on your system, so don't worry about that)\n\nThen install *py36-pip*, which is the python module manager for python 3 (here for python 3.6, but you can also use *py35-pip* if you prefer, any pip for Python version 3.5 or superior will work). Run, as root:\n\n.. code::\n\n    pkg install py36-pip\n\nFinally you can install mjail. Run, as root:\n\n.. code::\n\n    pip-3.6 install mjail\n\n---------------\nInitialization\n---------------\n\nBefore creating your first jail, you must initialize your system. This is a simple command. Run as root:\n\n.. code::\n\n   mjail init\n\nThis will, among other things, create a local virtual network interface ``lo8`` on your host for use by the jails.\nBy default, the ``10.240.0.0/12`` IPv4 range, and a randomly generated IPv6 site local network, are used for the jails.\n\nIf you want to use a different IPv4 range, you can specify it using the ``--ip4-network`` option.\nIf you want to use a different IPv6 range, you can specify it using the ``--ip6-network`` option.\n\nThe preceding command was equivalent to:\n\n.. code::\n\n    mjail init --ip4-network 10.240.0.0/12\n\n\n-----------------------------\nJails creation and management\n-----------------------------\n\nCreate a jail\n--------------\n\n.. code::\n\n    mjail create cooljail\n\nThis automatically gives the jail an IPv4 address and an IPv6 address in the local jail network, and it automatically starts the jail. The name of this jail is \"cooljail\". You will be able to use this name later on to stop the jail, start it or delete it for example. This is also the hostname of the jail.\n\nIf you want your jail to have an IPv4 address but no IPv6 address, use:\n\n.. code::\n\n    mjail create cooljail4 --ip4-only\n\nIf you want your jail to have an IPv6 address but not IPv4 address, use:\n\n.. code::\n\n    mjail create cooljail6 --ip6-only\n\nYou can check the list of jails that are currently running:\n\n.. code::\n\n    jls\n\n    JID  IP Address      Hostname                      Path\n    2    10.240.0.2      cooljail                     /var/mjail/instances/cooljail\n    3    10.240.0.3      cooljail4                    /var/mjail/instances/cooljail4\n    4                    cooljail6                    /var/mjail/instances/cooljail6\n\nTo check what IPv6 addresses have been assigned to your jails, use:\n\n.. code::\n\n    jls -v host.hostname ip6.addr\n\n    cooljail fd48:6132:e79f:4124::2\n    cooljail4 -\n    cooljail6 fd48:6132:e79f:4124::3\n\n\nIf you don't want the jail to start immediately, use the ``--no-start`` option:\n\n.. code:: sh\n\n    mjail create cooljail --no-start\n\nStop a jail\n------------\n\n.. code::\n\n    mjail stop cooljail\n\nDelete a jail\n--------------\n\n.. code::\n\n    mjail delete uncooljail\n\nStart a jail\n------------\n\nIf you have stopped a jail, or if you have created one using the ``--no-start`` option, your jail isn't running. Sad! To start it, run:\n\n.. code::\n\n    mjail start cooljail\n\nExecute a command inside a jail\n-------------------------------\n\n.. code::\n\n    mjail exec <jail_name> <command> [<arguments>...]\n\nFor example:\n\n.. code::\n\n    mjail exec cooljail cat /var/log/nginx/access.log\n\n\nStart a shell inside the jail\n------------------------------\n\n.. code::\n\n    # mjail shell cooljail\n\n    root@cooljail:/ # echo \"I'm inside the jail\"\n    I'm inside the jail\n\n\nCreate a jail that's accessible via ssh\n---------------------------------------\n\nFor that you'll need a public/private ssh key pair. If you don't have one already, you can create one using the  following command (run this on your laptop, not on the remote server, as private keys shouldn't be stored on the server you want to access):\n\n.. code:: sh\n\n    $ ssh-keygen -f my-cool-key\n\nYou'll get two files. The private key is contained in ``my-cool-key`` and the public key is contained in ``my-cool-key.pub``.\n\n.. code:: sh\n\n    $ cat my-coolkey.pub\n\n    ssh-rsa AAAAB3N...G7xAQt4LpCaEh/D+UpoChnJOXKV9 user@host\n\n\nAssuming your public key looks like this,\n\n.. code::\n\n    MY_PUBLIC_KEY='ssh-rsa AAAAB3N...G7xAQt4LpCaEh/D+UpoChnJOXKV9 user@host'\n\nyou can create a jail that's accessible via ssh over a port of your choice issuing this single command:\n\n.. code::\n\n    # mjail create cooljail --ssh-box \"$MY_PUBLIC_KEY\" port 4444\n\nNote that the jail is not facing the internet directly. `mjail` just instructs the `pf` firewall to redirect the ssh traffic over the port of your choice to the ssh daemon running inside the jail.\n\nDon't choose the same ssh port for your jail as the ssh port of the host. *mjail* wouldn't allow it since it would make you lose access to the host!\n\n\nThen you can access your jail just like it was a new dedicated server.\n\n.. code::\n\n    ssh -p 4444 root@xx.xx.xx.xx\n\nwhere xx.xx.xx.xx is the ip address of your host.\n\nThat's assuming you've added your ssh private key to the ssh-agent on your laptop using ``ssh-add``.\nIf not, just use:\n\n.. code::\n\n    ssh -i /path/to/my-cool-key -p 4444 root@xx.xx.xx.xx\n\n\nAdding ssh access to a jail\n----------------------------\n\nIf you created a jail using a simple ``mjail create myjail`` command, it has no ssh daemon running and you can't access it using ssh. To enable ssh access to the jail from the internet, use:\n\n.. code::\n\n    mjail set-up-sshd <jail_name> <public_key> port <host_port>\n\nwhere:\n    - ``<jail_name>`` is, well, the name of the jail\n    - ``<public_key>`` is your public key as a string (for example ``'ssh-rsa AAAAB3N...G7xAQt4LpCaEh/D+UpoChnJOXKV9 user@host'``). If you generated your key using ``ssh-keygen`` it's the content of your ``key.pub`` file.\n    - ``<host_port>``: the port of the host that you will connect to in order to connect to the ssh-daemon of the jail. Use a non common port, for exemple 4444. **Never use the same ssh port as the ssh port of the host or you'll lose ssh access to the host**.\n\n\nRedirect an internet facing port from the host to a jail\n--------------------------------------------------------\n\nJails created with `mjail` never face the internet directly. They have an ip on a local, virtual network interface, inside the host.\nSo how can you, say, run an internet server, such as Apache or Nginx inside a jail and access it from the internet?\n\nBy redirecting traffic from a port of the host to a port of the jail.\n\nThis is done with a simple command. Say you're running Nginx on port 80 inside your jail and you want Nginx to be accessible from the internet. You want to redirect the host's incoming traffic on port 80 to the port 80 of the jail.\nThis can be done using the command:\n\n.. code::\n\n    mjail rdr tcp 80 to cooljail 80\n\nThe general form of this command is\n\n.. code::\n\n    mjail rdr (tcp|udp) <internet_facing_host_port> to <jail_name> <jail_port>\n\nOf course, the ports don't need to be the same on the host and on the jail. If, for example, inside the jail you're running a Tornado web application on port 8080 and want to make it public on port 80 of the host, you'd issue a:\n\n.. code::\n\n    mjail rdr tcp 80 to cooljail 8080\n\nYou can cancel the redirection by running:\n\n.. code::\n\n    mjail cancel-rdr tcp 80\n\nPackages\n---------\n\nUse the `pkg` command inside the jail to install packages. There is no difference with what you'd do if you weren't inside a jail. Each jail manages its own packages. So, you can for example, spawn a shell inside your jail, or connect to your jail using ssh, and then install the packages you want.\n\nThis way, when you develop scripts that install packages, you don't have to worry about your script running inside a jail or not.\n\n\nBase system updates\n-------------------\n\nBase system updates have to be done from outside the jail.\n\nTo update the base system of a jail with the latest security patches:\n\n.. code::\n\n    mjail freebsd-update <jail_name>\n\nSometimes, it's required to upgrade to a new FreeBSD version because the one you're running no longer receives security patches. You can do that with:\n\n.. code::\n\n    mjail freebsd-update <jail_name> -r <to_version>\n\nFor example, if your jail is running FreeBSD 11.1, you can upgrade to 11.2\n\n.. code::\n\n    mjail freebsd-update cooljail -r 11.2\n\nOnly minor upgrades are supported (ie version 11.1 to 11.2, but not 11.x to 12.x) and even these haven't been thorougly tested at the moment. So, please regard it as an experimental feature.\n\n-----------\nGitHub repo\n-----------\n\nhttps://github.com/leforestier/mjail\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/leforestier/mjail",
        "keywords": "jail",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "mjail",
        "package_url": "https://pypi.org/project/mjail/",
        "platform": "",
        "project_url": "https://pypi.org/project/mjail/",
        "project_urls": {
            "Homepage": "https://github.com/leforestier/mjail"
        },
        "release_url": "https://pypi.org/project/mjail/0.3.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Command line tool to create and manage FreeBSD jails",
        "version": "0.3.0"
    },
    "last_serial": 5501967,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a49ab2330c4d7ac82640c49c3ef6ac02",
                    "sha256": "372fb35f184cdec7ff854dab46b546b7c164a67a05a210807f07c2a48ce93836"
                },
                "downloads": -1,
                "filename": "mjail-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "a49ab2330c4d7ac82640c49c3ef6ac02",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16667,
                "upload_time": "2018-06-10T16:11:12",
                "url": "https://files.pythonhosted.org/packages/e2/54/e4f98a1e6009617d9cbd18cae8286a7cf9b8b6acda01a406b25fcba65b0d/mjail-0.1.0.tar.gz"
            }
        ],
        "0.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3b41b140c2b1331c90d81c6d184aff4d",
                    "sha256": "e34fac169fcfa1b002ae27e874b4465c3a0b8fbca848c0e460f7af1960d88962"
                },
                "downloads": -1,
                "filename": "mjail-0.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "3b41b140c2b1331c90d81c6d184aff4d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16745,
                "upload_time": "2019-03-18T16:21:11",
                "url": "https://files.pythonhosted.org/packages/d4/9d/b83ba154fab11419a6eaf5f3572cde914dbf6edf68b173feca4d22f318f9/mjail-0.1.1.tar.gz"
            }
        ],
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a9bd7cdf755c5a3a24c75880f5125a82",
                    "sha256": "f73bc5f4bab455bb3b0cc5f372b67f3d54f87b00c969acd5257f20f86cb9f767"
                },
                "downloads": -1,
                "filename": "mjail-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "a9bd7cdf755c5a3a24c75880f5125a82",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17732,
                "upload_time": "2019-07-02T19:05:33",
                "url": "https://files.pythonhosted.org/packages/01/1f/92adca58836039c4bf9890264f282383d8abde35cf1eb15241d4cc4c95cd/mjail-0.2.0.tar.gz"
            }
        ],
        "0.3.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9570c8a9637292ad80db65ac9043e995",
                    "sha256": "40e354d0552a7701e633d3ca43305b533247329ac5d5dfe4696141ad69ab267d"
                },
                "downloads": -1,
                "filename": "mjail-0.3.0.tar.gz",
                "has_sig": false,
                "md5_digest": "9570c8a9637292ad80db65ac9043e995",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17619,
                "upload_time": "2019-07-08T16:12:10",
                "url": "https://files.pythonhosted.org/packages/49/c4/524e71ad5c76a23e82c08f6ac0c2ca555c6a51d7c6ca57dac67e8a3dd6b2/mjail-0.3.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "9570c8a9637292ad80db65ac9043e995",
                "sha256": "40e354d0552a7701e633d3ca43305b533247329ac5d5dfe4696141ad69ab267d"
            },
            "downloads": -1,
            "filename": "mjail-0.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "9570c8a9637292ad80db65ac9043e995",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 17619,
            "upload_time": "2019-07-08T16:12:10",
            "url": "https://files.pythonhosted.org/packages/49/c4/524e71ad5c76a23e82c08f6ac0c2ca555c6a51d7c6ca57dac67e8a3dd6b2/mjail-0.3.0.tar.gz"
        }
    ]
}