Host Configuration

In order to be able to use the pbm client effectively, we need to configure the Petabridge.Cmd.Host to listen for incoming connections on a reachable IP address and port. The Petabridg.Cmd.Host will bind to 0.0.0.0 by default, which should be a safe choice that can work for both local use (localhost) and remote use (some reachable IP in your network.)

Launching `Petabridge.Cmd.Host`

The first step to getting the Petabridge.Cmd.Host up and running on one of your Akka.NET services is to install the Petabridge.Cmd.Host NuGet package.

> install-package Petabridge.Cmd.Host

Using Akka.Hosting

Akka.Hosting is a HOCON-less approach to configuring and instantiating Akka.NET applications, and it's the easiest way to configure Petabridge.Cmd inside your ActorSystem:

using var host = await (new HostBuilder().ConfigureServices((context, collection) =>
{
    collection.AddAkka("PbmSys", builder =>
    {
        builder.WithRemoting("localhost", 29909)
            .WithClustering(new ClusterOptions(){ SeedNodes = new[]{ "akka.tcp://PbmSys@localhost:29909" }})
        .AddPetabridgeCmd(
                new PetabridgeCmdOptions(){ Host = "localhost", Port = 8222}, // optional - customize pbm bindings 
                cmd =>
        {
            cmd.RegisterCommandPalette(new RemoteCommands());
            cmd.RegisterCommandPalette(ClusterCommands.Instance);
        });
    });
}).StartAsync());

You can register all of your CommandPalette instances using the builder and Petabridge.Cmd will be started up automatically. All HOCON values can still be used to configure binding addresses.

Default HOCON Values

Like most parts of Akka.NET, Petabridge.Cmd.Host is configured via HOCON.

##################################
# petabridge.cmd Reference Config File #
##################################

petabridge.cmd{
	# default IP address used to listen for incoming petabridge.cmd client connections
	# should be a safe default as it listens on "all network interfaces".
	host = "0.0.0.0"

	# default port number used to listen for incoming petabridge.cmd client connections
	port = 9110

	# when true, logs all loaded palettes on startup
	log-palettes-on-startup = on
}

As you can see, the HOCON required by Petabridge.Cmd.Host is pretty simple. All of these values will be provided by default even if you don't add this HOCON to your ActorSystem's startup HOCON configuration. But if you want to override or customize any of those values, make sure you add the petabridge.cmd section to the root of your configuration.

Adding Petabridge.Cmd to `App/Web.Config`

If you'd like to have your Petabridge.Cmd.Host settings picked up automatically via your App.config or Web.Config, you can do this by simply adding the Akka HOCON configuration section to your app.config, like so:

<configuration>
  <configSections>
    <section name="akka" type="Akka.Configuration.Hocon.AkkaConfigurationSection, Akka" />

Once you have that added, you can add in the HOCON section to your App.config and include any settings you wish to pass onto Petabridge.Cmd.Host there:

<?xml version="1.0" encoding="utf-8"?>

<configuration>
  <configSections>
    <section name="akka" type="Akka.Configuration.Hocon.AkkaConfigurationSection, Akka" />
  </configSections>
  <akka>
    <hocon>
      <![CDATA[
          petabridge.cmd{
	          # disable logging palettes on startup
	          log-palettes-on-startup = off
          }
      
          akka {
            loglevel = DEBUG
            actor {
              provider = "Akka.Cluster.ClusterActorRefProvider, Akka.Cluster"
            }
            
            remote {
              log-remote-lifecycle-events = DEBUG
              helios.tcp {
                #public-hostname = "localhost"
                hostname = 127.0.0.1
                port = 14321
              }
            }

            cluster {
              roles = ["petabridge.cmd"] 
            }
          }
      ]]>
    </hocon>
  </akka>
</configuration>

Starting `PetabridgeCmd` Plugin

In order to active Petabridge.Cmd.Host inside your Akka.NET application, you need to make the following call inside your application:

private static void Main(string[] args)
{
    using (var a = ActorSystem.Create("Foo"))
    {
        var cmd = PetabridgeCmd.Get(a);
        cmd.Start();
        a.WhenTerminated.Wait();
    }
}

By calling PetabridgeCmd.Get you will get a reference to the Petabridg.Cmd.Host itself, and this method will always return the same PetabridgeCmd instance for the same ActorSystem.

Once you have access to the PetabridgeCmd object, you can load additional command palettes to register additional commands with your host. After you've registered all of the command palettes you wish to expose to pbm clients, call PetabridgeCmd.Start() to turn on the host and it will begin listening for incoming connections from pbm clients.

If your network setup was successful, you should see the following line appear in your Akka.NET logs:

[INFO][3/31/2017 3:53:13 PM][Thread 0019][[akka://MySys/user/petabridge.cmd#1808597773]] petabridge.cmd host bound to [[::ffff:0:0]:9110]

Network Configuration

Petabridge.Cmd.Host's default values should be able to work in any environment, but if you need to modify those values then this section is for you.

When your pbm clients need to be able to connect to remote Akka.NET hosts, such as ones running in a data center or an on-premise test environment, you need to ensure that both of the following are true:

petabridge.cmd.host resolves to a reachable IP address that can be accessed from outside the same machine that the Akka.NET process is running on;
petabridge.cmd.port must be accessible through the firewall, as it will be accepting an inbound connection from the outside.

NOTE: We do allow you to set petabridge.cmd.host with a DNS hostname, and that hostname will be resolved to an IP address and bound by the socket (since TCP and UDP don't natively support DNS). However, you will (deservedly) receive an angry warning message from the Petabridge.Cmd.Host if you do this, because 99/100 times binding a socket to a DNS does not work. In order for a socket to be able to bind to a domain name, that domain must be resolvable to the machine's local IP address.

Connecting the `pbm` to `Petabridge.Cmd.Host`

Once you've configured your PetabridgeCmd plugin to run on your Akka.NET application, you can now connect to it via the pbm commandline via the following syntax:

> pbm {ip}:{port} [module] [command] [arguments...n]

Or if you just want to enter interactive mode (what most users usually do)

> pbm {ip}:{port}

From there you'll receive a confirmation message if you were able to connect successfully.

pbm successfully connecting to Petabridge.Cmd.Host

Host Configuration

Launching Petabridge.Cmd.Host