=================================
Fabric Frequently Asked Questions
=================================
 
This is a dev-oriented list of FAQs from users. Once we get to maybe 10 or
more, turn this into an actual document. (Would rather not have a user facing
FAQ doc with only one or two entries, and too lazy to brainstorm a bunch of
anticipated FAQs right now...)
 
1. Why do I sometimes see ``err: stdin: is not a tty``?
=======================================================
 
This message is typically generated by programs such as ``biff`` or ``mesg``
lurking within your remote user's ``.profile`` or ``.bashrc`` files (or any
other such files, including system-wide ones.) Fabric's default mode of
operation involves executing the Bash shell in "login mode", which causes these
files to be executed.
 
Because Fabric also doesn't bother asking the remote end for a tty by default
(as it's not usually necessary) programs fired within your startup files, which
expect a tty to be present, will complain -- and thus, stderr output about
"stdin is not a tty" or similar.
 
There are multiple ways to deal with this problem:
 
* Find and remove or comment out the offending program call. If the program was
  not added by you on purpose and is simply a legacy of the operating system,
  this may be safe to do, and is the simplest approach.
* Override ``env.shell`` to remove the ``-l`` flag. This should tell Bash not
  to load your startup files. If you don't depend on the contents of your
  startup files (such as aliases or whatnot) this may be a good solution.
* Pass ``pty=True`` to `run` or `sudo`, which will force allocation of a
  pseudo-tty on the remote end, and hopefully cause the offending program to be
  less cranky.
 
 
2. Why can't I run programs in the background with ``&``? It makes Fabric hang.
===============================================================================
 
Because Fabric executes a shell on the remote end for each invocation of
``run`` or ``sudo``, techniques like backgrounding (or using ``cd``, but see
the `cd` context manager for help on that) will not work as expected.
Backgrounded processes still prevent the calling shell from exiting until they
stop running, and this in turn prevents Fabric from continuing on with its own
execution.
 
If you truly need to run a process in the "background" and are unable to
properly `daemonize
<http://en.wikipedia.org/wiki/Daemon_(computer_software)>`_, you may want to
look into GNU Screen (widely available in package managers or preinstalled)
which can easily serve the same purpose. A trivial example (``yes`` is a
simple Unix app that simply prints the word "yes" forever until killed)::
 
    run('screen -d -m "yes"')
 
Such a call will effectively fork the ``yes`` program into a detached
``screen`` session, which will no longer be associated with the calling shell,
and thus your Fabric task will continue executing as intended.
 
 
3. My remote system doesn't have ``bash`` installed by default, do I need to install ``bash``?
==============================================================================================
 
While Fabric is written with ``bash`` in mind, it's not an absolute
requirement.  Simply change ``env.shell`` to call your desired shell, and
include an argument similar to ``bash``'s ``-c`` argument, which allows us to
build shell commands of the form::
 
    /bin/bash -l -c "<command string here>"
 
where ``/bin/bash -l -c`` is the default value of ``env.shell``.
 
.. note::
 
    The ``-l`` argument specifices a login shell and is not absolutely
    required, merely convenient in many situations. Some shells lack the option
    entirely and it may be safely omitted in such cases.
 
A relatively safe baseline is to call ``/bin/sh``, which may call the original
``sh`` binary, or (on some systems) ``csh``, and give it the ``-c``
argument, like so::
 
    from fabric.api import env
 
    env.shell = "/bin/sh -c"
 
This has been shown to work on FreeBSD and may work on other systems as well.
 
 
4. I'm sometimes incorrectly asked for a passphrase instead of a password.
==========================================================================
 
Due to a bug of sorts in our SSH layer (Paramiko), it's not currently possible
for Fabric to always accurately detect the type of authentication needed. We
have to try and guess whether we're being asked for a private key passphrase or
a remote server password, and in some cases our guess ends up being wrong.
 
The most common such situation is where you, the local user, appear to have an
SSH keychain agent running, but the remote server is not able to honor your SSH
key, e.g. you haven't yet transferred the public key over or are using an
incorrect username. In this situation, Fabric will prompt you with "Please
enter passphrase for private key", but the text you enter is actually being
sent to the remote end's password authentication.
 
We hope to address this in future releases, either by doing heavier
introspection of Paramiko or patching Paramiko itself.