YAAC Command-Line Options

There are several options that can be specified on the Java command line when launching YAAC to modify its operation, in addition to standard JVM options. The YAAC-specific options appear on the command line after the -jar YAAC.jar part of the command.

java [-JVM_options] -jar YAAC.jar [-YAAC_options]

The most obvious JVM options relevant to YAAC are the -Xmx and -D options. The former specifies the maximum amount of heap memory Java is allowed to use. For YAAC, this typically should be at least 256m (256 megabytes), and at least 1024 megabytes when importing/compiling the whole-planet OpenStreetMap file. Smaller amounts can be used for tiny systems like the Raspberry Pi if the amount of incoming data (and/or persistence time thereof) is limited.

There are a few YAAC-specific JVM system properties that can be defined with the -D option to override certain defaults (primarily in the OpenStreetMap importer logic), using the -Dpropertyname=value syntax.

property namevalue meaning
alt.tile.dir Specifies the path to a directory where scratch index files for OpenStreetMap data importing are stored. By default, such files are stored in the configured tile directory; this option should be used when another physical disk is available for the scratch files, so that importing will not be slowed by excessive disk head seeks. There is no benefit in specifying this if the system has only one physical disk drive, and potential additional performance impairment if specifying a different partition on the same disk.
dated.tile.dir Specify when using the File->OpenStreetMap->Download PreImported Tiles command that a different subdirectory on the YAAC author's website should be used to download tiles. By default, the author makes pre-imported tile files available in the tiledir subdirectory at the https://www.ka2ddo.org/ka2ddo/ URL. If, for some reason, the current download is defective, the previous download directory can be used; the naming convention is tiledir_yyyymmdd, where yyyymmdd is the date of the OpenStreetMap download file used to create the tile directory.
dont.purge.temp If the value is "true", don't delete the temporary files when the import is completed. By default, the several gigabytes (potentially) of scratch files are deleted when the import completes. These files are not of use to anyone who is not developing changes to the importer code.
generate.named.bbox.file If the value is "true", generate an additional debugging file during OSM XML import which logs all map bounding boxes at various geopolitical levels. Not functional for PBF imports.
keep.unrenderable.osm.attributes If the value is "true", don't discard certain OpenStreetMap attributes that are helpful in analyzing the OSM data but are not actually used in rendering the map. This will cause generated tile files to be somewhat larger, due to preserving the additional attributes, and will therefore negatively impact OSM rendering times.
skip.osm.xml.parse If the value is "true", go directly to the sorting of imported tiles, skipping the XML or PBF parsing step. This is useful to preserve work if YAAC is shut down after parsing is complete but before the generated tiles are sorted and moved in place of previous versions of the operational .ways and .nodes files.
use.multi.osm.thread If defined (regardless of what value is specified for the property) and your system has at least 4 CPU cores available to the Java runtime, YAAC will use an alternate version of the OpenStreetMap renderer that uses parallel threads to read the .ways and .nodes files from disk and compute the rendering. Note that this is only useful if you have a slow disk drive and slow multi-core processor, such that YAAC can render while it is reading, rather than alternately reading the map tile files and rendering them in a single rendering thread. This is experimental, and not guaranteed to improve map rendering performance relative to the single-thread renderer.

The command-line options specific to YAAC are:

option namemeaning
-clear Erase all of the YAAC configuration data for this profile; if for the nameless profile, erase everything. YAAC will behave as if it was newly installed on a clean system, offering the option of running the configuration wizard to initially configure YAAC.
-clearBulletins Erase all persisted bulletin messages originated by this copy of YAAC in this profile.
-clearObjects Erase all persisted object definitions originated by this copy of YAAC in this profile.
-clearPorts Erase all of the interface port definitions (TNCs, GPSs, weather stations, APRS-IS connections, etc.) in this profile. YAAC will ask if you want to run the configuration wizard to define new ports.
-clearWindows Erase all of the memorized positions and sizes of different window types in YAAC in this profile, and let the operating system window manager and YAAC use default placements and sizes.
-debug Turn on extra tracing messages in the YAAC error log. May impair YAAC's performance due to the extra logging.
-debug:debugcategory[,debugcategory...] Turn on selected extra tracing messages in the YAAC error log, rather than enabling all debug messages. Categories are specified as a comma-separated list of category names. May impair YAAC's performance due to the extra logging. Some debug categories include:
  • all - same as specifying just the -debug option without a category list
  • AGWPE - log state change and keep-alive events in the AGWPE port driver (note this category name is uppercase)
  • aprs - log APRS protocol events
  • ax25 - log AX.25 protocol events
  • awt - log Java Abstract Widget Toolkit (AWT) user interface events
  • filter - log filter changes caused by user actions
  • gps - log GPS debugging events
  • gui - log YAAC GUI events other than low-level AWT events
  • nws - log weather alert processing errors
  • osm - log OpenStreetMap map rendering milestones (used to measure rendering performance)
Plugins can define additional tracing categories; check their documentation for details.
-gui Force YAAC to try to use a GUI display. By default, YAAC will attempt to open the graphical windows if a graphical environment is available (on Microsoft Windows and Macintosh OS X, or on Linux and Unix systems where an X server is available).
-gui:firstWindowType Force YAAC to try to use a GUI display (as with the plain -gui option), but starting with the specified type of window. By default, the first YAAC UI window will be the geographical map with the map controls above the actual map and text message sending controls below the map. The available first window types are:
mapdisplay the default geographical map window
stationlistdisplay the Station/Object tabular display window
helplist all the available choices for first windows, then terminate YAAC
Note that some YAAC plugins may provide additional views that are candidates for being first windows, so check their documentation and/or the output from -gui:help to see what choices are available.
-nogui Force YAAC to run without a GUI. Not all functionality will be available. Useful when using YAAC as a stand-alone digipeater or I-gate where a screen is not available or needed, but YAAC must be configured in -gui mode prior to running in -nogui mode.
-profile profilename Run YAAC with the named alternate named configuration profile. By default, YAAC will use the configuration stored in the nameless profile. The name is arbitrary, and can consist of letters, numbers, underscores, hyphens, and a few other punctuation characters; if spaces are used in the name, the name may need to be quoted to prevent the shell from ignoring the part of the name after the first space.
-storepass password Specify the password for opening the keystore. Necessary when running in -nogui mode when using the SSL APRS-IS port driver, where the authentication credentials must be extracted from the keystore. Note that this can be a security risk, as the password can displayed by system utilities that report the command lines of currently executing commands. If possible, use the -promptpass option instead.
-promptpass Specify that YAAC should prompt for the keystore password at the console used to invoke YAAC. Necessary when running in -nogui mode when using the SSL APRS-IS port driver, where the authentication credentials must be extracted from the keystore. This does nothing if the YAAC startup environment does not have a standard input file to prompt on and read the password from; as such, YAAC will try to prompt in the GUI when the password is required, which will fail if in -nogui mode.
-tempTileDir tiledir_path Specify a non-configured path to the directory tree where pre-imported OpenStreetMap tile files and USGS SRTM terrain files are stored. Typically used only on DVD-ROM or USB memory stick distributions of YAAC, so that sample map data can be provided on the distribution medium.