HADR Simulator Command Line Options

Run simhadr with no argument for a brief description of command line options. Options and keywords (such as "-role", "-flushSize", SYNC, NEARSYNC) are case insensitive. Case is used in documentation for ease of reading (for example: "-sockSndBuf").

Required Options

  • -role option specifies the role of the process. Start primary process on primary host machine and start standby process on standby host machine. The two processes will connect to each other via TCP. You can start either process first.
  • -lhost, -lport, -rhost, -rport are equivalent to DB2 configuration parameters HADR_LOCAL_HOST, HADR_LOCAL_SVC, HADR_REMOTE_HOST and HADR_REMOTE_SVC. These are the TCP addresses of primary and standby. Note that while the simulator accepts both host name and IP address for host argument, it accepts only port number for port argument (Real HADR accepts both port number and service name).

Basic Options

  • -n and -t arguments control the length of the simulation run. They are accepted only on the primary. You can control the length by number of flushes (-n), or by time (-t). Once primary reaches the limit, it will disconnect from the standby and end the run. Standby will detect the disconnection and end its run too. The default is 4 seconds of time limit and unlimited number of flushes.

During a run, you may send SIGINT (usually by pressing Control-C) to the primary any time to stop the simulation. Upon the signal, the primary will stop the run and the usual simulation result will be printed on both primary and standby. Note: SIGINT and Control-C works on both Unix and Windows.

  • -syncmode specifies the HADR sychronization mode. It is equivalent to DB2 configuration parameter HADR_SYNCMODE. Syncmode, remote catchup (RCU), and flush size are propagated from primary to standby. They are accepted only on the primary side.
  • -rcu tells simhadr to simulate remote catchup (RCU) state log shipping. The default behavior is to simulate peer state, using the specified sync mode, unless the mode is superAsync. Specifying "-syncmode superAsync" is identical to specifying "-rcu" because superAsync mode always runs in RCU state.
  • -flushSize specifies size of log flushes in unit of 4k byte log pages. Default is 16 for peer state and 16 for remote catchup. See "flush size" section in Simulation Parameters and Scenarios for more info.
  • -hadrBufSize sets standby recv buffer size in unit of 4k byte log pages. Default is 4 times flush size.
  • -target sets target log rate to specified MBytes/sec. Default infinity. This is useful when you want to throttle the log rate. For example, you are testing network stability rather than throughput. Applicable on the primary only.
  • -verbose gives you detailed info for each write, send, recv, and congestion. In most cases (especially when simhadr is writing to a terminal), the extra info will significantly slow down the simulation. Do not use -verbose for performance runs. Use only for per message debugging.

Network Options

  • -sockSndBuf and -sockRcvBuf set socket send or recv buffer size. These parameters are equivalent to DB2 registry variable DB2_HADR_SOSNDBUF and DB2_HADR_SORCVBUF. The default is system assigned size.
  • -nagle turns on nagle (combining send requests). In real HADR, nagle is always disabled. Nagle reduces total amount of network traffic, at the cost of application response time. This option lets you experiment on the impact of nagle.
  • -block tells the simulator to use blocking send and receive. Real HADR always uses nonblocking send and receive. This option lets you test network throughput in blocking mode. On properly configured systems, there should be little difference between blocking and nonblocking mode. Note: Primary and standby need not have the same -block option. You can use -block only on one side.
  • -bind, By default, the simulator does not bind standby socket's local end when it connects to the primary. Thus while the remote end of the socket is bound on the primary's local host and port (because primary listens on the address and standby connects to it), the socket's local end address is assigned by the standby host machine. Normally, the standby machine assigns a local IP that is on the best route to the primary end. The assigned IP may not be the canonical address of the standby machine. In most cases, it will be the address of the standby's HADR_LOCAL_HOST, because that address should be the best local end to reach the primary. In rare cases, such as misconfigured routing table, the assigned local end may cause inefficient network routing. You may use -bind option to force the standby to bind its local end to the local host argument of standby. Note: This option is for diagnostics only. Real HADR has no option to force standby local binding.

Disk Options

  • -write Creates, then writes to a file with specified name (name can include path) to test disk write performance. No network operations are done. Network options are ignored. As in real DB2, synchronous write is used (write() does not return until data is on disk). Write size can be controlled via -flushSize option. Simulation run time can be controlled via -n or -t option. If -verbose is on, a message will be printed on each write. Upon completion, the file is left for user inspection and removal.
  • -read Reads a file with specified name (name can include path) to test disk read performance. No network operations are done. Network options are ignored. Read size can be controlled via -flushSize option. Simulation run time can be controlled via -n or -t option. If -verbose is on, a message will be printed on each read. Typically, "-write" is used first to create a file, then "-read" is used to read the file. Read will stop when EOF is reached or -n/-t limit is reached.
  • -cache Enables file system caching for read/write test. By default, direct IO (no caching) is used. Special file systems such as virtual file system (/tmp on some Unix systems) may require -cache option because they do not support direct IO. In real DB2, registry variable DB2_LOGGER_NON_BUFFERED_IO controls logger caching behavior. The -cache option generally has little impact on write performance, but has big impact on read performance. Recommended setting for simhadr is to use default (disable caching).
  • -disk specifies disk speed using two parameters: data rate in MBytes/sec and per IO overhead in seconds. The default is infinitely fast disk (disk read/write takes no time). Thus if you do not specify -disk option, the simulation will only reflect network bottleneck (disk is usually not the bottleneck in log shipping). For RCU and SUPERASYNC mode primary side, use the slower of read/write speed, because the primary needs to read and write logs. For all other cases, use write speed (both primary and standby write logs).

Simulator Timing Options

  • -spin tells simhadr to use specified spin time to compensate for sleep overhead. Default measures sleep overhead on the system. Simhadr uses sleep (actually, its variation of nanosleep() on Unix and Sleep() (millisecond sleep) on Windows) to simulate write time. However, the OS only guarantees that the process will sleep no less than requested time. Actual sleep time is usually longer. When the OS wakes up the process, it may take some time for the process to actually run on a CPU. For accurate timing, simhadr will request less sleep time and top off the sleep time with CPU spinning. The auto measured sleep overhead usually works well. If you see too many warnings from simhadr about actual sleep time longer than requested time, increase spin time.
  • -testSleep tests accuracy of specified sleep time. It tests how well the sleep-and-spin method works. This options is used to test -spin settings.