net.i2p.router
Class Router

java.lang.Object
  extended by net.i2p.router.Router
All Implemented Interfaces:
RouterClock.ClockShiftListener

public class Router
extends Object
implements RouterClock.ClockShiftListener

Main driver for the router. For embedded use, instantiate and then call runRouter().


Field Summary
static char CAPABILITY_BW_UNLIMITED
           
static char CAPABILITY_BW12
           
static char CAPABILITY_BW128
           
static char CAPABILITY_BW256
           
static char CAPABILITY_BW32
           
static char CAPABILITY_BW512
           
static char CAPABILITY_BW64
           
static char CAPABILITY_NEW_TUNNEL
          Deprecated. unused
static char CAPABILITY_REACHABLE
           
static char CAPABILITY_UNREACHABLE
           
static long CLOCK_FUDGE_FACTOR
          let clocks be off by 1 minute
static int COALESCE_TIME
          coalesce stats this often - should be a little less than one minute, so the graphs get updated
static int DEFAULT_SHARE_PERCENTAGE
           
static int EXIT_GRACEFUL
          shut down after all tunnels are gone
static int EXIT_GRACEFUL_RESTART
          shut down after all tunnels are gone, and tell the wrapper to restart
static int EXIT_HARD
          shut down immediately
static int EXIT_HARD_RESTART
          shut down immediately, and tell the wrapper to restart
static int EXIT_OOM
          shut down immediately
static int NETWORK_ID
          used to differentiate routerInfo files on different networks
static String PROP_BANDWIDTH_SHARE_PERCENTAGE
           
static String PROP_CONFIG_FILE
           
static String PROP_DYNAMIC_KEYS
           
static String PROP_FORCE_BWCLASS
          for testing
static String PROP_FORCE_UNREACHABLE
          for testing
static String PROP_HIDDEN
          this puts an 'H' in your routerInfo
static String PROP_HIDDEN_HIDDEN
          this does not put an 'H' in your routerInfo
 Object routerInfoFileLock
          not for external use
static String UPDATE_FILE
           
 
Constructor Summary
Router()
          Instantiation only.
Router(Properties envProps)
          Instantiation only.
Router(String configFilename)
          Instantiation only.
Router(String configFilename, Properties envProps)
          Instantiation only.
 
Method Summary
 void addCapabilities(RouterInfo ri)
          For building our RI.
 void cancelGracefulShutdown()
          Cancel any prior request to shut the router down gracefully.
static void clearCaches()
          Not for external use.
 void clockShift(long delta)
          The clock shift listener.
 EventLog eventLog()
           
 int get15sRate()
          Max of inbound and outbound rate in bytes per second
 int get15sRate(boolean outboundOnly)
          When outboundOnly is false, outbound rate in bytes per second.
 int get15sRateIn()
          Inbound rate in bytes per second
 int get1mRate()
          Max of inbound and outbound rate in bytes per second
 int get1mRate(boolean outboundOnly)
          When outboundOnly is false, outbound rate in bytes per second.
 int get1mRateIn()
          Inbound rate in bytes per second
 int get1sRate()
          Max of inbound and outbound rate in bytes per second
 int get1sRate(boolean outboundOnly)
          When outboundOnly is false, outbound rate in bytes per second.
 int get1sRateIn()
          Inbound rate in bytes per second
 int get5mRate()
          Max of inbound and outbound rate in bytes per second
 int get5mRate(boolean outboundOnly)
          When outboundOnly is false, outbound rate in bytes per second.
 String getConfigFilename()
           
 Map<String,String> getConfigMap()
           
 String getConfigSetting(String name)
           
 Set<String> getConfigSettings()
           
 RouterContext getContext()
          Non-null, but take care when accessing context items before runRouter() is called as the context will not be initialized.
 boolean getHigherVersionSeen()
          Deprecated. unused
 boolean getKillVMOnEnd()
          Deprecated. unused
 RouterInfo getRouterInfo()
          Our current router info.
 double getSharePercentage()
          What fraction of the bandwidth specified in our bandwidth limits should we allow to be consumed by participating tunnels?
 long getShutdownTimeRemaining()
          How long until the graceful shutdown will kill us?
 long getUptime()
          wall clock uptime
 long getWhenStarted()
          Used only by routerconsole..
 boolean gracefulShutdownInProgress()
          Is a graceful shutdown in progress? This may be cancelled.
 boolean isAlive()
          True during the initial start, but false during a soft restart.
 boolean isFinalShutdownInProgress()
          Is a final shutdown in progress? This may not be cancelled.
 boolean isHidden()
           
 void killKeys()
          Not for external use.
static void main(String[] args)
          Usage: Router [rebuild] No other options allowed, for now Instantiates Router(), and either installs updates and exits, or calls runRouter().
 void readConfig()
          This updates the config with all settings found in the file.
 void rebuildNewIdentity()
          Rebuild a new identity the hard way - delete all of our old identity files, then reboot the router.
 void rebuildRouterInfo()
          Rebuild and republish our routerInfo since something significant has changed.
 void rebuildRouterInfo(boolean blockingRebuild)
          Rebuild and republish our routerInfo since something significant has changed.
 void removeConfigSetting(String name)
          Deprecated. use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)
 void restart()
          A "soft" restart, primarily of the comm system, after a port change or large step-change in system time.
 void runRouter()
          This must be called after instantiation.
 boolean saveConfig()
          Save the current config options (returning true if save was successful, false otherwise) Synchronized with file read in getConfig()
 boolean saveConfig(Map toAdd, Collection<String> toRemove)
          Updates the current config and then saves it.
 boolean saveConfig(String name, String value)
          Updates the current config with the given key/value and then saves it.
 int scheduledGracefulExitCode()
          What exit code do we plan on using when we shut down (or -1, if there isn't a graceful shutdown planned)
 void setConfigFilename(String filename)
          Deprecated. unused
 void setConfigSetting(String name, String value)
          Deprecated. use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)
 void setExplTunnelsReady()
          Only for Tunnel Building, after we have non-zero-hop expl.
 void setHigherVersionSeen(boolean seen)
          Deprecated. unused
 void setIsAlive()
          Only for Restarter, after soft restart is complete.
 void setKillVMOnEnd(boolean shouldDie)
          Configure the router to kill the JVM when the router shuts down, as well as whether to explicitly halt the JVM during the hard fail process.
 void setNetDbReady()
          Only for NetDB, after RIs are loaded.
 void setRouterInfo(RouterInfo info)
          Caller must ensure info is valid - no validation done here.
 void shutdown(int exitCode)
          Shutdown with no chance of cancellation.
 void shutdown2(int exitCode)
          Cancel the JVM runtime hook before calling this.
 void shutdownGracefully()
          Non-blocking shutdown.
 void shutdownGracefully(int exitCode)
          Non-blocking shutdown.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

routerInfoFileLock

public final Object routerInfoFileLock
not for external use


PROP_CONFIG_FILE

public static final String PROP_CONFIG_FILE
See Also:
Constant Field Values

CLOCK_FUDGE_FACTOR

public static final long CLOCK_FUDGE_FACTOR
let clocks be off by 1 minute

See Also:
Constant Field Values

NETWORK_ID

public static final int NETWORK_ID
used to differentiate routerInfo files on different networks

See Also:
Constant Field Values

COALESCE_TIME

public static final int COALESCE_TIME
coalesce stats this often - should be a little less than one minute, so the graphs get updated

See Also:
Constant Field Values

PROP_HIDDEN

public static final String PROP_HIDDEN
this puts an 'H' in your routerInfo

See Also:
Constant Field Values

PROP_HIDDEN_HIDDEN

public static final String PROP_HIDDEN_HIDDEN
this does not put an 'H' in your routerInfo

See Also:
Constant Field Values

PROP_DYNAMIC_KEYS

public static final String PROP_DYNAMIC_KEYS
See Also:
Constant Field Values

UPDATE_FILE

public static final String UPDATE_FILE
See Also:
Constant Field Values

CAPABILITY_BW12

public static final char CAPABILITY_BW12
See Also:
Constant Field Values

CAPABILITY_BW32

public static final char CAPABILITY_BW32
See Also:
Constant Field Values

CAPABILITY_BW64

public static final char CAPABILITY_BW64
See Also:
Constant Field Values

CAPABILITY_BW128

public static final char CAPABILITY_BW128
See Also:
Constant Field Values

CAPABILITY_BW256

public static final char CAPABILITY_BW256
See Also:
Constant Field Values

CAPABILITY_BW512

public static final char CAPABILITY_BW512
Since:
0.9.18
See Also:
Constant Field Values

CAPABILITY_BW_UNLIMITED

public static final char CAPABILITY_BW_UNLIMITED
Since:
0.9.18
See Also:
Constant Field Values

PROP_FORCE_BWCLASS

public static final String PROP_FORCE_BWCLASS
for testing

See Also:
Constant Field Values

CAPABILITY_REACHABLE

public static final char CAPABILITY_REACHABLE
See Also:
Constant Field Values

CAPABILITY_UNREACHABLE

public static final char CAPABILITY_UNREACHABLE
See Also:
Constant Field Values

PROP_FORCE_UNREACHABLE

public static final String PROP_FORCE_UNREACHABLE
for testing

See Also:
Constant Field Values

CAPABILITY_NEW_TUNNEL

public static final char CAPABILITY_NEW_TUNNEL
Deprecated. unused
See Also:
Constant Field Values

EXIT_GRACEFUL

public static final int EXIT_GRACEFUL
shut down after all tunnels are gone

See Also:
Constant Field Values

EXIT_HARD

public static final int EXIT_HARD
shut down immediately

See Also:
Constant Field Values

EXIT_OOM

public static final int EXIT_OOM
shut down immediately

See Also:
Constant Field Values

EXIT_HARD_RESTART

public static final int EXIT_HARD_RESTART
shut down immediately, and tell the wrapper to restart

See Also:
Constant Field Values

EXIT_GRACEFUL_RESTART

public static final int EXIT_GRACEFUL_RESTART
shut down after all tunnels are gone, and tell the wrapper to restart

See Also:
Constant Field Values

PROP_BANDWIDTH_SHARE_PERCENTAGE

public static final String PROP_BANDWIDTH_SHARE_PERCENTAGE
See Also:
Constant Field Values

DEFAULT_SHARE_PERCENTAGE

public static final int DEFAULT_SHARE_PERCENTAGE
See Also:
Constant Field Values
Constructor Detail

Router

public Router()
Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. Config file name is "router.config" unless router.configLocation set in system properties.

Throws:
IllegalStateException - since 0.9.19 if another router with this config is running

Router

public Router(Properties envProps)
Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. Config file name is "router.config" unless router.configLocation set in envProps or system properties.

Parameters:
envProps - may be null
Throws:
IllegalStateException - since 0.9.19 if another router with this config is running

Router

public Router(String configFilename)
Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up.

Parameters:
configFilename - may be null
Throws:
IllegalStateException - since 0.9.19 if another router with this config is running

Router

public Router(String configFilename,
              Properties envProps)
Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. If configFilename is non-null, configuration is read in from there. Else if envProps is non-null, configuration is read in from the location given in the router.configLocation property. Else it's read in from the System property router.configLocation. Else from the file "router.config". The most important properties are i2p.dir.base (the install directory, may be read-only) and i2p.dir.config (the user's configuration/data directory). i2p.dir.base defaults to user.dir (CWD) but should almost always be set. i2p.dir.config default depends on OS, user name (to detect if running as a service or not), and auto-detection of whether there appears to be previous data files in the base dir. See WorkingDir for details. If the config dir does not exist, it will be created, and files migrated from the base dir, in this constructor. If files in an existing config dir indicate that another router is already running with this directory, the constructor will delay for several seconds to be sure, and then call System.exit(-1).

Parameters:
configFilename - may be null
envProps - may be null
Throws:
IllegalStateException - since 0.9.19 if another router with this config is running
Method Detail

clearCaches

public static final void clearCaches()
Not for external use.

Since:
0.8.8

setKillVMOnEnd

public void setKillVMOnEnd(boolean shouldDie)
Configure the router to kill the JVM when the router shuts down, as well as whether to explicitly halt the JVM during the hard fail process. Defaults to true. Set to false for embedded before calling runRouter()


getKillVMOnEnd

public boolean getKillVMOnEnd()
Deprecated. unused


getConfigFilename

public String getConfigFilename()
Returns:
absolute path

setConfigFilename

public void setConfigFilename(String filename)
Deprecated. unused


getConfigSetting

public String getConfigSetting(String name)

setConfigSetting

public void setConfigSetting(String name,
                             String value)
Deprecated. use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)

Warning, race between here and saveConfig(), saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove) is recommended.

Since:
0.8.13

removeConfigSetting

public void removeConfigSetting(String name)
Deprecated. use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)

Warning, race between here and saveConfig(), saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove) is recommended.

Since:
0.8.13

getConfigSettings

public Set<String> getConfigSettings()
Returns:
unmodifiable Set, unsorted

getConfigMap

public Map<String,String> getConfigMap()
Returns:
unmodifiable Map, unsorted

getRouterInfo

public RouterInfo getRouterInfo()
Our current router info. Warning, may be null if called very early.


setRouterInfo

public void setRouterInfo(RouterInfo info)
Caller must ensure info is valid - no validation done here. Not for external use.


getHigherVersionSeen

public boolean getHigherVersionSeen()
Deprecated. unused

True if the router has tried to communicate with another router who is running a higher incompatible protocol version.


setHigherVersionSeen

public void setHigherVersionSeen(boolean seen)
Deprecated. unused

True if the router has tried to communicate with another router who is running a higher incompatible protocol version.


getWhenStarted

public long getWhenStarted()
Used only by routerconsole.. to be deprecated?


getUptime

public long getUptime()
wall clock uptime


getContext

public RouterContext getContext()
Non-null, but take care when accessing context items before runRouter() is called as the context will not be initialized.

Returns:
non-null

runRouter

public void runRouter()
This must be called after instantiation. Starts the threads. Does not install updates. This is for embedded use. Standard standalone installation uses main() instead, which checks for updates and then calls this. This may take quite a while, especially if NTP fails or the system lacks entropy

Throws:
IllegalStateException - if called more than once
Since:
public as of 0.9 for Android and other embedded uses

readConfig

public void readConfig()
This updates the config with all settings found in the file. It does not clear the config first, so settings not found in the file will remain in the config. This is synchronized with saveConfig(). Not for external use.


isAlive

public boolean isAlive()
True during the initial start, but false during a soft restart.


setIsAlive

public void setIsAlive()
Only for Restarter, after soft restart is complete. Not for external use.

Since:
0.8.12

setNetDbReady

public void setNetDbReady()
Only for NetDB, after RIs are loaded. Not for external use.

Since:
0.9.18

setExplTunnelsReady

public void setExplTunnelsReady()
Only for Tunnel Building, after we have non-zero-hop expl. tunnels. Not for external use.

Since:
0.9.18

gracefulShutdownInProgress

public boolean gracefulShutdownInProgress()
Is a graceful shutdown in progress? This may be cancelled. Note that this also returns true if an uncancellable final shutdown is in progress.


isFinalShutdownInProgress

public boolean isFinalShutdownInProgress()
Is a final shutdown in progress? This may not be cancelled.

Since:
0.8.12

rebuildRouterInfo

public void rebuildRouterInfo()
Rebuild and republish our routerInfo since something significant has changed. Not for external use.


rebuildRouterInfo

public void rebuildRouterInfo(boolean blockingRebuild)
Rebuild and republish our routerInfo since something significant has changed. Not for external use.


addCapabilities

public void addCapabilities(RouterInfo ri)
For building our RI. Not for external use. This does not publish the ri. This does not use anything in the ri (i.e. it can be freshly constructed) TODO just return a string instead of passing in the RI? See PublishLocalRouterInfoJob.

Parameters:
ri - an unpublished ri we are generating.

isHidden

public boolean isHidden()

eventLog

public EventLog eventLog()
Since:
0.9.3

killKeys

public void killKeys()
Not for external use.


rebuildNewIdentity

public void rebuildNewIdentity()
Rebuild a new identity the hard way - delete all of our old identity files, then reboot the router. Calls exit(), never returns. Not for external use.


shutdown

public void shutdown(int exitCode)
Shutdown with no chance of cancellation. Blocking, will call exit() and not return unless setKillVMOnExit(false) was previously called, or a final shutdown is already in progress. May take several seconds as it runs all the shutdown hooks.

Parameters:
exitCode - one of the EXIT_* values, non-negative
Throws:
IllegalArgumentException - if exitCode negative

shutdown2

public void shutdown2(int exitCode)
Cancel the JVM runtime hook before calling this. Called by the ShutdownHook. NOT to be called by others, use shutdown().

Parameters:
exitCode - one of the EXIT_* values, non-negative
Throws:
IllegalArgumentException - if exitCode negative

shutdownGracefully

public void shutdownGracefully()
Non-blocking shutdown. Call this if we want the router to kill itself as soon as we aren't participating in any more tunnels (etc). This will not block and doesn't guarantee any particular time frame for shutting down. To shut the router down immediately, use shutdown(int). If you want to cancel the graceful shutdown (prior to actual shutdown ;), call cancelGracefulShutdown(). Exit code will be EXIT_GRACEFUL. Shutdown delay will be from zero to 11 minutes.


shutdownGracefully

public void shutdownGracefully(int exitCode)
Non-blocking shutdown. Call this with EXIT_HARD or EXIT_HARD_RESTART for a non-blocking, hard, non-graceful shutdown with a brief delay to allow a UI response Returns silently if a final shutdown is already in progress.

Parameters:
exitCode - one of the EXIT_* values, non-negative
Throws:
IllegalArgumentException - if exitCode negative

cancelGracefulShutdown

public void cancelGracefulShutdown()
Cancel any prior request to shut the router down gracefully. Returns silently if a final shutdown is already in progress.


scheduledGracefulExitCode

public int scheduledGracefulExitCode()
What exit code do we plan on using when we shut down (or -1, if there isn't a graceful shutdown planned)

Returns:
one of the EXIT_* values or -1

getShutdownTimeRemaining

public long getShutdownTimeRemaining()
How long until the graceful shutdown will kill us?

Returns:
-1 if no shutdown in progress.

saveConfig

public boolean saveConfig()
Save the current config options (returning true if save was successful, false otherwise) Synchronized with file read in getConfig()


saveConfig

public boolean saveConfig(String name,
                          String value)
Updates the current config with the given key/value and then saves it. Prevents a race in the interval between setConfigSetting() / removeConfigSetting() and saveConfig(), Synchronized with getConfig() / saveConfig()

Parameters:
name - setting to add/change/remove before saving
value - if non-null, updated value; if null, setting will be removed
Returns:
success
Since:
0.8.13

saveConfig

public boolean saveConfig(Map toAdd,
                          Collection<String> toRemove)
Updates the current config and then saves it. Prevents a race in the interval between setConfigSetting() / removeConfigSetting() and saveConfig(), Synchronized with getConfig() / saveConfig()

Parameters:
toAdd - settings to add/change before saving, may be null or empty
toRemove - settings to remove before saving, may be null or empty
Returns:
success
Since:
0.8.13

clockShift

public void clockShift(long delta)
The clock shift listener. Restart the router if we should.

Specified by:
clockShift in interface RouterClock.ClockShiftListener
Parameters:
delta - The system clock and adjusted clock just changed by this much, in milliseconds (approximately)
Since:
0.8.8

restart

public void restart()
A "soft" restart, primarily of the comm system, after a port change or large step-change in system time. Does not stop the whole JVM, so it is safe even in the absence of the wrapper. This is not a graceful restart - all peer connections are dropped immediately. As of 0.8.8, this returns immediately and does the actual restart in a separate thread. Poll isAlive() if you need to know when the restart is complete. Not recommended for external use.


main

public static void main(String[] args)
Usage: Router [rebuild] No other options allowed, for now Instantiates Router(), and either installs updates and exits, or calls runRouter(). Not recommended for embedded use. Applications bundling I2P should instantiate a Router and call runRouter().

Parameters:
args - null ok
Throws:
IllegalArgumentException

getSharePercentage

public double getSharePercentage()
What fraction of the bandwidth specified in our bandwidth limits should we allow to be consumed by participating tunnels?

Returns:
a number less than one, not a percentage!

get1sRate

public int get1sRate()
Max of inbound and outbound rate in bytes per second


get1sRate

public int get1sRate(boolean outboundOnly)
When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.


get1sRateIn

public int get1sRateIn()
Inbound rate in bytes per second


get15sRate

public int get15sRate()
Max of inbound and outbound rate in bytes per second


get15sRate

public int get15sRate(boolean outboundOnly)
When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.


get15sRateIn

public int get15sRateIn()
Inbound rate in bytes per second


get1mRate

public int get1mRate()
Max of inbound and outbound rate in bytes per second


get1mRate

public int get1mRate(boolean outboundOnly)
When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.


get1mRateIn

public int get1mRateIn()
Inbound rate in bytes per second


get5mRate

public int get5mRate()
Max of inbound and outbound rate in bytes per second


get5mRate

public int get5mRate(boolean outboundOnly)
When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.