Frequently Asked Questions

How much memory does Buju require?
It depends. Java has a reputation of requiring a lot of memory. Add to that a memory-intensive application (such as graphics manipulation or large spreadsheet I/O) and you may want Gigs of memory available, and may need to tune Java heap size and garbage collection parameters.

The number of concurrent connections may also make a difference.

Buju itself doesn't appear to take up that much memory. You might want to start with the default memory settings in Java, and increase them as you see a need. Java startup parameters are specified in buju/conf/wrapper.conf.

Can I run multiple Buju servers?
Yes, as long as each one is on a different host, or on the same host using different ports.

Having a production Buju server running on one port and an occasional test server on another port or even another host is standard procedure.

So how do I start a second 'test' Buju server?
Good question. Perhaps the cleanest way is to copy the buju directory to a new test directory, say bujutest. (You don't really need the docs subdirectory.) Then edit the bujutest/conf/buju.properties file and change the port. You may want to review other configuration options, too.

This is also a good procedure for testing new versions of Buju with your application.

If you want multiple Buju *services* on the same host, perhaps as part of a failover scheme, you have to do a little configuration and name editing. First, you should probably still copy the buju directory to something like buju2. Then, if you are on a Windows server, modify buju2/conf/wrapper.conf like so:

wrapper.ntservice.name=Buju2

There may be some other options you want to modify, too.

Then you should follow the installation instructions, except that where they refer to directory buju, you should substitute buju2. If you are using Linux/Unix, your suggested start-up link names will have to be slightly changed to make them unique.

When someone actually tries this and discovers the inadequacies in these instructions, I hope they will fill in the details for the rest of us.

How do I restart Buju without killing all of the current connections?
Perceptive question. Stopping or restarting the service at the operating system level shuts down the JVM, in which not only the server but current connections to the server live. They are all summarily executed.

Of course, if you are wanting to restart the server just to get your changes to users and passwords, allowed client hosts, or the interpreter initialization script recognized, you should be using the admin command .refreshServer.

But if you must restart the server without killing connections, you can issue the admin command .restartServer. This stops the current server instance from accepting any more connections, but it starts up a new server using the same configuration, which will immediately begin servicing new connections. The old connections remain functional. The only bad thing is that old connections and new connections will not share any interpreters, including the admin interpreter. Anything that relies on the sharing of interpreters, including the maximum connections limit checking done in the admin interpreter, may not work as expected.

It might be possible to preserve the admin interpreter from one server instance to its successor. But the drawback there is that the admin initialization script would not get reloaded and the admin namespace would not get re-initialized, both of which are desirable if you are making changes to the admin script. But I won't be surprised if someone figures out how to have it both ways.

See also Refreshing or Restarting the Buju Service.

Can I package Buju with my commercial product?
Yes, as long as you preserve, abide by and distribute all legal notices such as copyright, license, and warranty (or, in fact, no warranty).

And while you are at it...

Can I modify Buju?
Yes. And please take the time to share your modifications with the rest of us.

How is SSL used?
By default, Buju uses Secure Socket Layer for socket communications between the server and the clients. The information required for SSL connections to be negotiated is stored in the Java keystore buju/conf/bujustore. Parameters in buju/conf/wrapper.conf point to this keystore. Buju uses a self-signed certificate to verify itself to the client. Buju does not ask the client to authenticate itself.

The client-side implementation of SSL may require that Buju authenticate itself. If this is the case, you can either:

• Try to turn off this requirement on the client. This leaves you vulnerable to what is called the man-in-the-middle security breach, but may be an acceptable risk for your own situation. The man-in-the-middle scenario places an agent between the client and the server during SSL negotiations, allowing that agent to read subsequent encrypted exchanges, or mimic the client or server in the exchange. The scenario requires someone to hack your TCP/IP network, which in itself probably opens up your network to more likely security risks than just an attack on Buju.
• Import the Buju self-signed X.509 certificate buju/conf/buju.cert into whatever trusted keystore your SSL implementation requires.

A Java client can use the provided trusted keystore buju/test/clientstore, as the buju/test executables do, or import the certificate from the provided X.509 self-signed certificate file buju/conf/buju.cert. However, your client-side SSL implementation is likely to be written in a language other than Java, and have its own trusted keystore equivalent. Importing buju/conf/buju.cert into that trusted keystore equivalent may require a little research on your part.

Can I change the buju/conf/bujustore keystore password?
Yes. You can launch the script buju/conf/keytool.bat to do so (Windows only, but a Linux/Unix equivalent won't be hard to figure out). There are actually two separate passwords which you must keep the same in order for Buju to work -- the keystore password and the key password for alias 'buju'. The script prompts you for both. You will also need to edit buju/conf/wrapper.conf to reflect your change, and restart Buju.

Can I regenerate buju/conf/bujustore, buju/test/clientstore and buju/conf/buju.cert?
Yes. If you edit the script buju/conf/keytool.bat, you will see several commands to do so, which are remarked out. Un-remark them and run the script (Windows only, but a Linux/Unix equivalent won't be hard to figure out). You may then need to edit buju/conf/wrapper.conf to reflect any changes you make, and then restart Buju.

How can I send and receive binary data?
If it's a large amount of data, such as a graphics file, you might want to transfer the data using a standard network data transfer protocol such as FTP, or if possible just store the data in a file on one side of the connection and read it in from the other side.

Otherwise, you need to convert the binary data to a human-readable string format, such as a hex string representation, before sending it over the network.

Every Buju interpreter has access, by default, to a convert command, which has two interior methods:

  String convert().toHexStringFrom(byte[] binary)
  byte[] binary convert().toByteArrayFrom(String hexString)

Use the first method before returning binary data from your Buju interpreter to the client, and the second method before using encoded data received from your client in your Buju interpreter.

Of course, you would need similar encoding or decoding operations in the client application. And hex encoding isn't the only possibility. Something like Base64 encoding, as provided by the biz.bbeans.util.BBase64 class, is more compressed, if you can find compatible Base64 encoding/decoding libraries for your client application to use.

Can Buju do callbacks?
No, not really. It operates more like a web server, accepting requests and sending responses. It can't "push" information to the client, nor can it execute code on the client.

What about doing a user interface through Buju?
Though the typical use of Buju will be as a "headless" server, you could run the server, or another instance of the server, in the user's login session. Then it could pop up windows and allow direct user interaction.

For example, if a user logs into his Windows computer and starts up Buju manually (or through some automated start-up process under that user's login) so it is running in a console window, any UI initiated in Buju should be visible to that user, just like any other Java program run by the user.

Where can I get more help?
Try the appropriate discussion group, or contact us directly. People are very willing to help, including the authors of Buju. But just remember that almost everyone has a day job. If your question specifically concerns BeanShell or Java Service Wrapper, or for that matter Java or your particular operating system, you might try getting help from forums dedicated to those subjects. Google it.

What's with the monkey?
What's with the penguin?