<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Flame: Foreign Location Automatic Module Exposer — Pyro 4.21 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '4.21',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Pyro 4.21 documentation" href="index.html" />
<link rel="next" title="Tips & Tricks" href="tipstricks.html" />
<link rel="prev" title="Errors and remote tracebacks" href="errors.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="tipstricks.html" title="Tips & Tricks"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="errors.html" title="Errors and remote tracebacks"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="flame-foreign-location-automatic-module-exposer">
<h1>Flame: Foreign Location Automatic Module Exposer<a class="headerlink" href="#flame-foreign-location-automatic-module-exposer" title="Permalink to this headline">¶</a></h1>
<img alt="_images/flammable.png" class="align-left" src="_images/flammable.png" />
<p>Pyro Flame is an easy way of exposing remote modules and builtins, and even a remote interactive
Python console. It is available since Pyro 4.10.
With Flame, you don’t need to write any server side code anymore, and still be
able to call objects, modules and other things on the remote machine.
Flame does this by giving a client direct access to any module or builtin that is available on the remote machine.</p>
<p>Flame can be found in the <a class="reference internal" href="api/flame.html#module-Pyro4.utils.flame" title="Pyro4.utils.flame"><tt class="xref py py-mod docutils literal"><span class="pre">Pyro4.utils.flame</span></tt></a> module.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Be very sure about what you are doing before enabling Flame.</p>
<p>Flame is disabled by default. You need to explicitly set a config item
to true, and start a Flame server yourself, to make it available.
This is because it allows client programs full access to <em>everything</em> on your system.
Only use it if you fully trust your environment and the clients that can connect to your machines.</p>
<p class="last">(Flame is also symbolic for burning server machines that got totally owned by malicious clients.)</p>
</div>
<div class="section" id="enabling-flame">
<h2>Enabling Flame<a class="headerlink" href="#enabling-flame" title="Permalink to this headline">¶</a></h2>
<p>Flame is actually a special Pyro object that is exposed via a normal Pyro daemon.
You need to start it explicitly in your daemon. This is done by calling a utility
function with your daemon that you want to enable flame on:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">Pyro4.utils.flame</span>
<span class="n">Pyro4</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">flame</span><span class="o">.</span><span class="n">start</span><span class="p">(</span><span class="n">daemon</span><span class="p">)</span>
</pre></div>
</div>
<p>Additionally, you have to make two configuration changes:</p>
<ul class="simple">
<li>set the <tt class="docutils literal"><span class="pre">FLAME_ENABLED</span></tt> config item to True</li>
<li>set the <tt class="docutils literal"><span class="pre">SERIALIZER</span></tt> config item to “pickle”</li>
</ul>
<p>You’ll have to explicitly enable Flame. When you don’t, you’ll
get an error when trying to start Flame. The config item is False by default
to avoid unintentionally running Flame servers.
Also, Flame requires the pickle serializer. It doesn’t work when using one of
the secure serializers, because it needs to be able to transfer custom python objects.</p>
</div>
<div class="section" id="command-line-server">
<h2>Command line server<a class="headerlink" href="#command-line-server" title="Permalink to this headline">¶</a></h2>
<p>There’s a little command line server program that will launch a flame enabled Pyro daemon,
to avoid the hassle of having to write a custom server program yourself everywhere you want
to provide a Flame server:</p>
<p><strong class="command">python -m Pyro4.utils.flameserver</strong></p>
<p>The command line arguments are similar to the echo server (see <a class="reference internal" href="commandline.html#command-line-echoserver"><em>Test echo server</em></a>).
Use <tt class="docutils literal"><span class="pre">-h</span></tt> to make it print a short help text. For the command line server you’ll also have
to set the <tt class="docutils literal"><span class="pre">FLAME_ENABLED</span></tt> config item to True, otherwise you’ll get an error when trying to start it.
Because we’re talking about command line clients, the most convenient way to do so is probably by
setting the environment variable in your shell: <tt class="docutils literal"><span class="pre">PYRO_FLAME_ENABLED=true</span></tt>.</p>
</div>
<div class="section" id="flame-object-and-examples">
<h2>Flame object and examples<a class="headerlink" href="#flame-object-and-examples" title="Permalink to this headline">¶</a></h2>
<p>A Flame server exposes a <tt class="docutils literal"><span class="pre">"Pyro.Flame"</span></tt> object (you can hardcode this name or use the
constant <a class="reference internal" href="api/constants.html#Pyro4.constants.FLAME_NAME" title="Pyro4.constants.FLAME_NAME"><tt class="xref py py-attr docutils literal"><span class="pre">Pyro4.constants.FLAME_NAME</span></tt></a>).
Its interface is described in the API documentation, see <a class="reference internal" href="api/flame.html#Pyro4.utils.flame.Flame" title="Pyro4.utils.flame.Flame"><tt class="xref py py-class docutils literal"><span class="pre">Pyro4.utils.flame.Flame</span></tt></a>.</p>
<p>Connecting to the flame server can be done as usual (by creating a Pyro proxy yourself)
or by using the convenience function <a class="reference internal" href="api/flame.html#Pyro4.utils.flame.connect" title="Pyro4.utils.flame.connect"><tt class="xref py py-func docutils literal"><span class="pre">Pyro4.utils.flame.connect()</span></tt></a>.
A little example follows. You have to have running flame server, and then you can write a client like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">Pyro4.utils.flame</span>
<span class="n">Pyro4</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">SERIALIZER</span> <span class="o">=</span> <span class="s">"pickle"</span> <span class="c"># flame requires pickle serializer</span>
<span class="n">flame</span> <span class="o">=</span> <span class="n">Pyro4</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">flame</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s">"hostname:9999"</span><span class="p">)</span> <span class="c"># or whatever the server runs at</span>
<span class="n">socketmodule</span> <span class="o">=</span> <span class="n">flame</span><span class="o">.</span><span class="n">module</span><span class="p">(</span><span class="s">"socket"</span><span class="p">)</span>
<span class="n">osmodule</span> <span class="o">=</span> <span class="n">flame</span><span class="o">.</span><span class="n">module</span><span class="p">(</span><span class="s">"os"</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"remote host name="</span><span class="p">,</span> <span class="n">socketmodule</span><span class="o">.</span><span class="n">gethostname</span><span class="p">()</span>
<span class="k">print</span> <span class="s">"remote server directory contents="</span><span class="p">,</span> <span class="n">osmodule</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="s">"."</span><span class="p">)</span>
<span class="n">flame</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="s">"import math"</span><span class="p">)</span>
<span class="n">root</span> <span class="o">=</span> <span class="n">flame</span><span class="o">.</span><span class="n">evaluate</span><span class="p">(</span><span class="s">"math.sqrt(500)"</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"calculated square root="</span><span class="p">,</span> <span class="n">root</span>
<span class="k">print</span> <span class="s">"remote exceptions also work"</span><span class="p">,</span> <span class="n">flame</span><span class="o">.</span><span class="n">evaluate</span><span class="p">(</span><span class="s">"1//0"</span><span class="p">)</span>
<span class="c"># print something on the remote std output</span>
<span class="n">flame</span><span class="o">.</span><span class="n">builtin</span><span class="p">(</span><span class="s">"print"</span><span class="p">)(</span><span class="s">"Hello there, remote server stdout!"</span><span class="p">)</span>
</pre></div>
</div>
<p>A remote interactive console can be started like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">flame</span><span class="o">.</span><span class="n">console</span><span class="p">()</span> <span class="k">as</span> <span class="n">console</span><span class="p">:</span>
<span class="n">console</span><span class="o">.</span><span class="n">interact</span><span class="p">()</span>
<span class="c"># ... you can repeat sessions if you want</span>
</pre></div>
</div>
<p>... which will print something like:</p>
<div class="highlight-python"><pre>Python 2.7.2 (default, Jun 12 2011, 20:46:48)
[GCC 4.2.1 (Apple Inc. build 5577)] on darwin
(Remote console on charon:9999)
>>> # type stuff here and it gets executed on the remote machine
>>> import socket
>>> socket.gethostname()
'charon.local'
>>> ^D
(Remote session ended)</pre>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>The <tt class="docutils literal"><span class="pre">getfile</span></tt> and <tt class="docutils literal"><span class="pre">sendfile</span></tt> functions can be used for <em>very</em> basic file transfer.</p>
<p class="last">The <tt class="docutils literal"><span class="pre">getmodule</span></tt> and <tt class="docutils literal"><span class="pre">sendmodule</span></tt> functions can be used to send module source files
to other machines so it is possible to execute code that wasn’t available before.
This is a <em>very</em> experimental replacement of the mobile code feature that Pyro 3.x had.
It also is a very easy way of totally owning the server because you can make it execute
anything you like. Be very careful.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="pyrolite.html"><em>Pyrolite - client library for Java and .NET</em></a> also supports convenient access to a Pyro Flame server. This includes the remote interactive console.</p>
</div>
<p>See the <tt class="file docutils literal"><span class="pre">flame</span></tt> example for example code including uploading module source code to the server.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/pyro.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Flame: Foreign Location Automatic Module Exposer</a><ul>
<li><a class="reference internal" href="#enabling-flame">Enabling Flame</a></li>
<li><a class="reference internal" href="#command-line-server">Command line server</a></li>
<li><a class="reference internal" href="#flame-object-and-examples">Flame object and examples</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="errors.html"
title="previous chapter">Errors and remote tracebacks</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tipstricks.html"
title="next chapter">Tips & Tricks</a></p>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="tipstricks.html" title="Tips & Tricks"
>next</a> |</li>
<li class="right" >
<a href="errors.html" title="Errors and remote tracebacks"
>previous</a> |</li>
<li><a href="index.html">Pyro 4.21 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Irmen de Jong.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
