README.txt
273 lines
| 8.3 KiB
| text/plain
|
TextLexer
|
r164 | .. -*- mode: rst; compile-command: "rst2html README.txt README.html" -*- | ||
|
r35 | |||
================= | ||||
|
r181 | Mercurial Keyring | ||
|
r35 | ================= | ||
|
r181 | Mercurial Keyring is a Mercurial_ extension used to securely save HTTP | ||
and SMTP authentication passwords in password databases (Gnome | ||||
Keyring, KDE KWallet, OSXKeyChain, Windows Vault etc). | ||||
With ``mercurial_keyring`` active, Mercurial remembers your passwords | ||||
and reuses them without prompting (as if you stored them in ``.hgrc``), | ||||
but password storage is reasonably secure. | ||||
Actual password storage is implemented by the keyring_ library, this | ||||
extension glues it to Mercurial. | ||||
|
r35 | |||
.. _keyring: http://pypi.python.org/pypi/keyring | ||||
|
r36 | .. _Mercurial: http://mercurial.selenic.com | ||
|
r35 | |||
How does it work | ||||
================ | ||||
|
r181 | On your first pull or push to HTTP url (or first email sent via given | ||
SMTP server), you are prompted for the password, just like bare | ||||
Mercurial does. But the password you entered is saved to appropriate | ||||
password database. On successive runs, whenever the password is | ||||
needed, ``mercurial_keyring`` checks for password in password | ||||
database, and uses it without troubling you. | ||||
|
r35 | |||
|
r181 | In case password turns out to be incorrect (for example, because you | ||
changed it, or entered it incorrectly), ``mercurial_keyring`` wipes | ||||
it, and prompts you again. | ||||
|
r35 | |||
|
r181 | You can use many passwords (for various remote urls). Saved passwords | ||
are identified by pair of username and url prefix. See below for | ||||
information how to configure those properly. | ||||
|
r37 | |||
|
r35 | Installation | ||
============ | ||||
|
r36 | Prerequisites | ||
------------- | ||||
|
r164 | This extension requires keyring_ and `mercurial_extension_utils`_ to | ||
work. In many cases both will be installed automatically while you | ||||
install `mercurial_keyring`_, but you may need to control the process. | ||||
The keyring_ library can usually be installed by:: | ||||
|
r35 | |||
|
r164 | pip install --user keyring | ||
|
r35 | |||
|
r164 | (or ``easy_install keyring``), but on some systems it is preferable to | ||
use official distribution archive. For example, on Debian and Ubuntu, | ||||
you may install ``python-keyring`` and either ``python-keyring-gnome`` | ||||
or ``python-keyring-kwallet`` packages:: | ||||
|
r35 | |||
|
r164 | sudo apt-get install python-keyring python-keyring-gnome | ||
(this will save you the need to provide working compiler and various | ||||
development libraries). | ||||
|
r36 | |||
|
r164 | The `mercurial_extension_utils`_ module is tiny Python-only module, | ||
which can be installed by:: | ||||
|
r57 | |||
|
r164 | pip install --user mercurial_extension_utils | ||
|
r180 | but in some cases (Windows…) require more care. See | ||
`mercurial_extension_utils`_ documentation. | ||||
|
r164 | |||
|
r57 | |||
|
r36 | Extension installation | ||
---------------------- | ||||
There are two possible ways of installing the extension: using PyPi package, | ||||
|
r164 | or using source clone. | ||
|
r36 | |||
|
r164 | To install as a package:: | ||
|
r36 | |||
|
r164 | pip install --user mercurial_keyring | ||
|
r36 | |||
|
r164 | (or ``sudo pip install mercurial_keyring`` for system-wide | ||
installation) and then enable it in ``~/.hgrc`` (or | ||||
``/etc/mercurial/hgrc`` or ``Mercurial.ini``) using:: | ||||
|
r36 | |||
[extensions] | ||||
mercurial_keyring = | ||||
|
r164 | To install as source clone, install keyring_ according to instructions above, then | ||
clone:: | ||||
hg clone https://bitbucket.org/Mekk/mercurial_keyring/ | ||||
hg clone https://bitbucket.org/Mekk/mercurial-extension_utils/ | ||||
|
r35 | |||
|
r164 | and configure Mercurial by telling it full path to the extension | ||
(in ):: | ||||
|
r35 | |||
[extensions] | ||||
|
r164 | mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py | ||
|
r35 | |||
|
r37 | .. _the code: | ||
.. _mercurial_keyring.py: http://bitbucket.org/Mekk/mercurial_keyring/src/tip/mercurial_keyring.py | ||||
|
r35 | Password backend configuration | ||
============================== | ||||
The library should usually pick the most appropriate password backend | ||||
without configuration. Still, if necessary, it can be configured using | ||||
|
r180 | ``keyringrc.cfg`` file. Refer to keyring_ docs for more details. | ||
.. note:: | ||||
|
r35 | |||
|
r180 | With current (as I write) keyring (5.6), this file is (on Linux) | ||
located at ``~/.local/share/python_keyring/keyringrc.cfg`` and | ||||
it's example content look like:: | ||||
[backend] | ||||
default-keyring=keyring.backends.Gnome.Keyring | ||||
# default-keyring=keyring.backends.kwallet.Keyring | ||||
For list of known backends run ``pydoc keyring.backends``. | ||||
|
r35 | |||
|
r181 | ``hgrc`` configuration (HTTP) | ||
|
r35 | =============================== | ||
|
r181 | Mercurial Keyring uses standard Mercurial ``[auth]`` configuration to | ||
detect your username (on given remote) and url prefix. You are | ||||
strongly advised to configure both. | ||||
Without the username ``mercurial_keyring`` can't save or restore | ||||
passwords, so it disables itself. | ||||
Without url prefix ``mercurial_keyring`` works, but binds passwords to | ||||
repository urls. That means you will have to (re)enter password for | ||||
every repository cloned from given remote (and that there will be many | ||||
copies of this password in secure storage). | ||||
Repository level configuration | ||||
------------------------------------ | ||||
|
r35 | Edit repository-local ``.hg/hgrc`` and save there the remote | ||
repository path and the username, but do not save the password. For | ||||
example: | ||||
:: | ||||
[paths] | ||||
myremote = https://my.server.com/hgrepo/someproject | ||||
[auth] | ||||
|
r181 | myremote.prefix = https://my.server.com/hgrepo | ||
myremote.username = John | ||||
|
r35 | |||
Simpler form with url-embedded name can also be used: | ||||
:: | ||||
[paths] | ||||
|
r181 | bitbucket = https://John@my.server.com/hgrepo/someproject/ | ||
|
r35 | |||
|
r181 | Note that all repositories sharing the same ``prefix`` share the same | ||
password. | ||||
|
r46 | |||
|
r181 | Mercurial allows also for password in ``.hg/hgrc`` (either given by | ||
``«prefix».password``, or embedded in url). If such password is found, | ||||
Mercurial Keyring disables itself so it is used. | ||||
|
r35 | |||
|
r181 | Account-level configuration | ||
--------------------------- | ||||
If you are consistent about remote repository nicknames, you can | ||||
configure the username in your `~/.hgrc` (`.hgrc` in your home | ||||
directory). For example, write there:: | ||||
|
r53 | |||
[auth] | ||||
acme.prefix = hg.acme.com/repositories | ||||
acme.username = johnny | ||||
acme.schemes = http https | ||||
|
r181 | bitbucket.prefix = https://bitbucket.org | ||
bitbucket.username = Mekk | ||||
mydep.prefix = https://dev.acmeorg.com | ||||
mydep.username = drmartin | ||||
|
r53 | |||
and as long as you will be using alias `acme` for repositories like | ||||
`https://hg.acme.com/repositories/my_beautiful_app`, username | ||||
|
r181 | `johnnny` will be used, and the same password reused. Similarly | ||
any ``hg push bitbucket`` will share the same password. | ||||
With such config repository-level ``.hg/hgrc`` need only contain | ||||
``[paths]``. | ||||
Additional advantage of this method is that it works also during | ||||
`clone`. | ||||
.. note:: | ||||
|
r53 | |||
|
r181 | Mercurial Keyring works well with `Path Pattern`_. On my setup I use:: | ||
|
r53 | |||
|
r181 | [path_pattern] | ||
bitbucket.local = ~/devel/{below} | ||||
bitbucket.remote = https://bitbucket.org/Mekk/{below:/=-} | ||||
so all my repositories understand ``hg push bitbucket`` without | ||||
any repository-level configuration. | ||||
``hgrc`` configuration (SMTP) | ||||
|
r35 | =============================== | ||
Edit either repository-local ``.hg/hgrc``, or ``~/.hgrc`` and set | ||||
|
r37 | there all standard email and smtp properties, including SMTP | ||
username, but without SMTP password. For example: | ||||
|
r35 | |||
:: | ||||
[email] | ||||
method = smtp | ||||
from = Joe Doe <Joe.Doe@remote.com> | ||||
[smtp] | ||||
host = smtp.gmail.com | ||||
port = 587 | ||||
username = JoeDoe@gmail.com | ||||
tls = true | ||||
|
r37 | Just as in case of HTTP, you *must* set username, but *must not* set | ||
password here to use the extension, in other cases it will revert to | ||||
the default behavior. | ||||
|
r35 | |||
Usage | ||||
===== | ||||
|
r36 | Configure the repository as above, then just ``hg pull``, ``hg push``, | ||
etc. You should be asked for the password only once (per every | ||||
|
r46 | username and remote repository prefix or url combination). | ||
|
r36 | Similarly, for email, configure as above and just ``hg email``. | ||
|
r46 | Again, you will be asked for the password once (per every username and | ||
email server address combination). | ||||
|
r35 | |||
Implementation details | ||||
====================== | ||||
|
r36 | The extension is monkey-patching the mercurial ``passwordmgr`` class | ||
to replace the find_user_password method. Detailed order of operations | ||||
|
r37 | is described in the comments inside `the code`_. | ||
|
r35 | |||
|
r155 | History | ||
========== | ||||
See `HISTORY.txt`_. | ||||
|
r35 | Development | ||
=========== | ||||
|
r36 | Development is tracked on BitBucket, see | ||
http://bitbucket.org/Mekk/mercurial_keyring/ | ||||
|
r35 | |||
Additional notes | ||||
================ | ||||
Information about this extension is also available | ||||
|
r36 | on Mercurial Wiki: http://mercurial.selenic.com/wiki/KeyringExtension | ||
|
r155 | |||
|
r157 | .. _HISTORY.txt: http://bitbucket.org/Mekk/mercurial_keyring/src/tip/HISTORY.txt | ||
|
r164 | .. _TortoiseHg: http://tortoisehg.bitbucket.org/ | ||
.. _Mercurial: http://mercurial.selenic.com | ||||
.. _mercurial_extension_utils: https://bitbucket.org/Mekk/mercurial-extension_utils/ | ||||
|
r181 | .. _Path Pattern: https://bitbucket.org/Mekk/mercurial-path_pattern/ | ||