== Install guide

Installing binaries:

* link:install_from_available_binary_packages.html[Installing from available binary packages]
* link:install_from_available_archives.html[Installing from available archives]

=== Manual build

* link:install_manual_build.html[Manual build]

=== Distribution notes
Honeycomb is packaged as a static set of jars, that are loaded by Honeycomb Main class, where pre-configured plugins are then started.

=== Footprint

Minimal footprint for Honeycomb infrastructure (without any plugins) at rest below 80Mb. For Honeycomb distribution with VPP related plugins, minimal footprint was observed below 110Mb.
The footprint varies depending on:

* VM load. Under heavier load, JVM tends to release some unused memory used during Honeycomb initialization.
* Northbound interface configuration (4 interfaces started by default: Restconf HTTP, HTTPS, Netconf TCP, SSH). Minimal footprint can be achieved by using only a single interface.
* JVM configuration. Minimal footprint can be achieved by using aggressive JVM memory options, e.g.: -client -Xms20m -Xmx32m -XX:MetaspaceSize=5m -XX:MaxMetaspaceSize=32m -XX:MaxMetaspaceExpansion=1m -Xss512k -XX:+UseSerialGC -Djava.compiler=NONE -Xverify:none -noverify
* Amount of data stored by Honeycomb.

=== Runtime Data

For purpose of following minimal setup, these parameters were used

 java -client -Xms5m -Xmx25m -XX:MetaspaceSize=5m -XX:MaxMetaspaceSize=42m -XX:MaxMetaspaceExpansion=1m -Xss512k -XX:+UseSerialGC -Djava.compiler=NONE -Xverify:none -noverify -jar

NOTE: In this setup, honeycomb is able to handle only transaction of limited size. If
usecase requires writing bigger data, params -Xmx and -XX:MaxMetaspaceSize should be increased.

==== Infrastructure

Following modules enables basic honeycomb functionality and
Restconf northbound interface

 io.fd.honeycomb.infra.distro.schema.YangBindingProviderModule
 io.fd.honeycomb.infra.distro.schema.SchemaModule
 io.fd.honeycomb.infra.distro.data.ConfigAndOperationalPipelineModule
 io.fd.honeycomb.infra.distro.data.context.ContextPipelineModule
 io.fd.honeycomb.infra.distro.initializer.InitializerPipelineModule
 io.fd.honeycomb.northbound.CredentialsModule
 io.fd.honeycomb.northbound.restconf.RestconfModule
 io.fd.honeycomb.infra.distro.cfgattrs.CfgAttrsModule

===== Configuration files

To enable just Restconf HTTP, in /config/restconf.json, set *restconf-https-enabled* to false

==== Plugins

Following modules enables honeycomb binding to all core vpp plugins

 io.fd.hc2vpp.common.integration.VppCommonModule
 io.fd.hc2vpp.management.VppManagementModule
 io.fd.hc2vpp.lisp.LispModule
 io.fd.hc2vpp.lisp.gpe.GpeModule
 io.fd.hc2vpp.v3po.V3poModule
 io.fd.hc2vpp.iface.role.InterfaceRoleModule
 io.fd.hc2vpp.l3.InterfaceL3Module
 io.fd.hc2vpp.l3.SubInterfaceL3Module
 io.fd.hc2vpp.l3.ProxyArpModule
 io.fd.hc2vpp.vpp.classifier.VppClassifierModule
 io.fd.hc2vpp.vpp.classifier.InterfaceClassifierAclModule
 io.fd.hc2vpp.vpp.classifier.SubInterfaceClassifierAclModule
 io.fd.hc2vpp.nat.NatModule
 io.fd.hc2vpp.routing.RoutingModule
 io.fd.hc2vpp.acl.AclModule
 io.fd.hc2vpp.dhcp.DhcpModule
 io.fd.hc2vpp.policer.PolicerModule

==== Data

In this minimal setup, honeycomb was able to handle

* max 2940 single rule acl's - using 120 bytes per acl
* max 250 multi rule acl's(20 rules per acls) - using 2688 bytes per acl
* max 7610 classify tables - using 24 bytes per acl
* 10000+ map resolvers - using 24 bytes per map resolver
* 500+ interfaces(Before it reaches vpp limit for configurable interfaces) - using 42 bytes per interface

NOTE: Memory consumption mentioned is size of raw objects that represents desired
configuration. It does not include objects used by transaction handling to process
such data.

At rest, honeycomb instance footprint was observed as ~ 95.3 MB. With any of the mentioned
data samples written, footprint reaches ~ 97.5 MB till instance runs out of memory.

IMPORTANT: These values were observed while attempting to write data in "one object per tx" fashion.
To be able to write mentioned data samples all at once, higher settings for -Xmx and -XX:MetaspaceSize are needed

