diff --git a/CHANGES b/CHANGES index 2488227d58..583a7220f3 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,24 @@ +2.3-440 | 2015-02-23 11:39:17 -0600 + + * Updating plugin docs to recent changes. (Robin Sommer) + + * Updating plugin tests to recent changes. (Robin Sommer) + + * Making plugin names case-insensitive for some internal comparisions. + Makes plugin system more tolerant against spelling inconsistencies + are hard to catch otherwise. (Robin Sommer) + + * Explicitly removing some old scripts on install that have moved + into plugins to prevent them causing confusion. (Robin Sommer) + + * BIT-1312: Removing setting installation plugin path from + bro-path-dev.sh. Also, adding to existing BRO_PLUGIN_PATH rather + than replacing. (Robin Sommer) + + * Creating the installation directory for plugins at install time. + (Robin Sommer) + 2.3-427 | 2015-02-20 13:49:33 -0800 * Removing dependency on PCAP_NETMASK_UNKNOWN to compile with diff --git a/CMakeLists.txt b/CMakeLists.txt index c0ff6c09d4..04ac197f74 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -31,12 +31,12 @@ configure_file(bro-path-dev.in ${CMAKE_CURRENT_BINARY_DIR}/bro-path-dev) file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bro-path-dev.sh "export BROPATH=`${CMAKE_CURRENT_BINARY_DIR}/bro-path-dev`\n" - "export BRO_PLUGIN_PATH=\"${CMAKE_CURRENT_BINARY_DIR}/src:${BRO_PLUGIN_INSTALL_PATH}\"\n" + "export BRO_PLUGIN_PATH=\"${CMAKE_CURRENT_BINARY_DIR}/src\":${BRO_PLUGIN_PATH}\n" "export PATH=\"${CMAKE_CURRENT_BINARY_DIR}/src\":$PATH\n") file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/bro-path-dev.csh "setenv BROPATH `${CMAKE_CURRENT_BINARY_DIR}/bro-path-dev`\n" - "setenv BRO_PLUGIN_PATH \"${CMAKE_CURRENT_BINARY_DIR}/src:${BRO_PLUGIN_INSTALL_PATH}\"\n" + "setenv BRO_PLUGIN_PATH \"${CMAKE_CURRENT_BINARY_DIR}/src\":${BRO_PLUGIN_PATH}\n" "setenv PATH \"${CMAKE_CURRENT_BINARY_DIR}/src\":$PATH\n") file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/VERSION" VERSION LIMIT_COUNT 1) diff --git a/VERSION b/VERSION index ceb17112a6..ee7ad29d7b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.3-427 +2.3-440 diff --git a/aux/binpac b/aux/binpac index 77a86591dc..87b7329093 160000 --- a/aux/binpac +++ b/aux/binpac @@ -1 +1 @@ -Subproject commit 77a86591dcf89d7252d3676d3f1199d6c927d073 +Subproject commit 87b732909383c6637437850a75012fe2e376fd10 diff --git a/aux/bro-aux b/aux/bro-aux index 0b713c027d..ccf606ef5d 160000 --- a/aux/bro-aux +++ b/aux/bro-aux @@ -1 +1 @@ -Subproject commit 0b713c027d3efaaca50e5df995c02656175573cd +Subproject commit ccf606ef5dcd2da55efcae2d15fe57fc0b438317 diff --git a/aux/broccoli b/aux/broccoli index d43cc790e5..7dca802aa8 160000 --- a/aux/broccoli +++ b/aux/broccoli @@ -1 +1 @@ -Subproject commit d43cc790e5b8709b5e032e52ad0e00936494739b +Subproject commit 7dca802aa8b803033dccc0e6ec9e92a98f709740 diff --git a/aux/broctl b/aux/broctl index 8c9b87bc73..d1c3c5de0f 160000 --- a/aux/broctl +++ b/aux/broctl @@ -1 +1 @@ -Subproject commit 8c9b87bc73e1ddaa304e3d89028c1e7b95d37a91 +Subproject commit d1c3c5de0f4e8cff923c076ce39d72a86798dbde diff --git a/aux/plugins b/aux/plugins index ad600b5bdc..14c78567d9 160000 --- a/aux/plugins +++ b/aux/plugins @@ -1 +1 @@ -Subproject commit ad600b5bdcd56a2723e323c0f2c8e1708956ca4f +Subproject commit 14c78567d971dc7fcdc84e36716a1ce5adaa2d56 diff --git a/cmake b/cmake index 1316c07f70..8c121c8449 160000 --- a/cmake +++ b/cmake @@ -1 +1 @@ -Subproject commit 1316c07f7059647b6c4a496ea36e4b83bb5d8f0f +Subproject commit 8c121c844953026fbaf051a1b065c1671ed47c5b diff --git a/doc/devel/plugins.rst b/doc/devel/plugins.rst index c703345891..5e488cfe01 100644 --- a/doc/devel/plugins.rst +++ b/doc/devel/plugins.rst @@ -3,7 +3,7 @@ Writing Bro Plugins =================== -Bro is internally moving to a plugin structure that enables extending +Bro internally provides plugin API that enables extending the system dynamically, without modifying the core code base. That way custom code remains self-contained and can be maintained, compiled, and installed independently. Currently, plugins can add the following @@ -42,18 +42,17 @@ certain structure. To get started, Bro's distribution provides a helper script ``aux/bro-aux/plugin-support/init-plugin`` that creates a skeleton plugin that can then be customized. Let's use that:: - # mkdir rot13-plugin - # cd rot13-plugin - # init-plugin Demo Rot13 + # init-plugin ./rot13-plugin Demo Rot13 -As you can see the script takes two arguments. The first is a -namespace the plugin will live in, and the second a descriptive name -for the plugin itself. Bro uses the combination of the two to identify -a plugin. The namespace serves to avoid naming conflicts between -plugins written by independent developers; pick, e.g., the name of -your organisation. The namespace ``Bro`` is reserved for functionality -distributed by the Bro Project. In our example, the plugin will be -called ``Demo::Rot13``. +As you can see, the script takes three arguments. The first is a +directory inside which the plugin skeleton will be created. The second +is the namespace the plugin will live in, and the third is a descriptive +name for the plugin itself relative to the namespace. Bro uses the +combination of namespace and name to identify a plugin. The namespace +serves to avoid naming conflicts between plugins written by independent +developers; pick, e.g., the name of your organisation. The namespace +``Bro`` is reserved for functionality distributed by the Bro Project. In +our example, the plugin will be called ``Demo::Rot13``. The ``init-plugin`` script puts a number of files in place. The full layout is described later. For now, all we need is @@ -61,7 +60,7 @@ layout is described later. For now, all we need is there as follows:: # cat src/rot13.bif - module CaesarCipher; + module Demo; function rot13%(s: string%) : string %{ @@ -82,18 +81,22 @@ The syntax of this file is just like any other ``*.bif`` file; we won't go into it here. Now we can already compile our plugin, we just need to tell the -configure script put in place by ``init-plugin`` where the Bro source -tree is located (Bro needs to have been built there first):: +configure script that ``init-plugin`` put in place where the Bro +source tree is located (Bro needs to have been built there first):: + # cd rot13-plugin # ./configure --bro-dist=/path/to/bro/dist && make [... cmake output ...] -Now our ``rot13-plugin`` directory has everything that it needs -for Bro to recognize it as a dynamic plugin. Once we point Bro to it, -it will pull it in automatically, as we can check with the ``-N`` +This builds the plugin in a subdirectory ``build/``. In fact, that +subdirectory *becomes* the plugin: when ``make`` finishes, ``build/`` +has everything it needs for Bro to recognize it as a dynamic plugin. + +Let's try that. Once we point Bro to the ``build/`` directory, it will +pull in our new plugin automatically, as we can check with the ``-N`` option:: - # export BRO_PLUGIN_PATH=/path/to/rot13-plugin + # export BRO_PLUGIN_PATH=/path/to/rot13-plugin/build # bro -N [...] Plugin: Demo::Rot13 - (dynamic, version 1) @@ -127,12 +130,12 @@ more verbose option ``-NN``:: # bro -NN [...] Plugin: Demo::Rot13 - Caesar cipher rotating a string's characters by 13 places. (dynamic, version 1) - [Function] CaesarCipher::rot13 + [Function] Demo::rot13 [...] There's our function. Now let's use it:: - # bro -e 'print CaesarCipher::rot13("Hello")' + # bro -e 'print Demo::rot13("Hello")' Uryyb It works. We next install the plugin along with Bro itself, so that it @@ -141,36 +144,40 @@ environment variable. If we first unset the variable, the function will no longer be available:: # unset BRO_PLUGIN_PATH - # bro -e 'print CaesarCipher::rot13("Hello")' - error in , line 1: unknown identifier CaesarCipher::rot13, at or near "CaesarCipher::rot13" + # bro -e 'print Demo::rot13("Hello")' + error in , line 1: unknown identifier Demo::rot13, at or near "Demo::rot13" Once we install it, it works again:: # make install - # bro -e 'print CaesarCipher::rot13("Hello")' + # bro -e 'print Demo::rot13("Hello")' Uryyb The installed version went into ``/lib/bro/plugins/Demo_Rot13``. -We can distribute the plugin in either source or binary form by using -the Makefile's ``sdist`` and ``bdist`` target, respectively. Both -create corrsponding tarballs:: +One can distribute the plugin independently of Bro for others to use. +To distribute in source form, just remove the ``build/`` (``make +distclean`` does that) and then tar up the whole ``rot13-plugin/`` +directory. Others then follow the same process as above after +unpacking. To distribute the plugin in binary form, the build process +conveniently creates a corresponding tarball in ``build/dist/``. In +this case, it's called ``Demo_Rot13-0.1.tar.gz``, with the version +number coming out of the ``VERSION`` file that ``init-plugin`` put +into place. The binary tarball has everything needed to run the +plugin, but no further source files. Optionally, one can include +further files by specifying them in the plugin's ``CMakeLists.txt`` +through the ``bro_plugin_dist_files`` macro; the skeleton does that +for ``README``, ``VERSION``, ``CHANGES``, and ``COPYING``. To use the +plugin through the binary tarball, just unpack it and point +``BRO_PLUGIN_PATH`` there; or copy it into +``/lib/bro/plugins/`` directly. - # make sdist - [...] - Source distribution in build/sdist/Demo_Rot13.tar.gz - - # make bdist - [...] - Binary distribution in build/Demo_Rot13-darwin-x86_64.tar.gz - -The source archive will contain everything in the plugin directory -except any generated files. The binary archive will contain anything -needed to install and run the plugin, i.e., just what ``make install`` -puts into place as well. As the binary distribution is -platform-dependent, its name includes the OS and architecture the -plugin was built on. +Before distributing your plugin, you should edit some of the meta +files that ``init-plugin`` puts in place. Edit ``README`` and +``VERSION``, and update ``CHANGES`` when you make changes. Also put a +license file in place as ``COPYING``; if BSD is fine, you find a +template in ``COPYING.edit-me``. Plugin Directory Layout ======================= @@ -179,7 +186,7 @@ A plugin's directory needs to follow a set of conventions so that Bro (1) recognizes it as a plugin, and (2) knows what to load. While ``init-plugin`` takes care of most of this, the following is the full story. We'll use ```` to represent a plugin's top-level -directory. +directory. With the skeleton, ```` corresponds to ``build/``. ``/__bro_plugin__`` A file that marks a directory as containing a Bro plugin. The file @@ -205,6 +212,8 @@ directory. Directory with auto-generated Bro scripts that declare the plugin's bif elements. The files here are produced by ``bifcl``. +Any other files in ```` are ignored by Bro. + By convention, a plugin should put its custom scripts into sub folders of ``scripts/``, i.e., ``scripts//