Common problems users experience can be found in the Frequently Asked Questions Section. If you cannot find the answer you need here, Benetech provides user support for free through firstname.lastname@example.org. Users can get the best support with problems by sending a good bug report.
If you are having trouble or Martus does something unexpected, please send a big report to email@example.com. Tell Benetech specifically
and include as many screenshots as possible. It is extremely helpful to include a copy of the console log.
Below are instructions to open a "console log" that displays additional information as Martus runs. This information is helpful to us in diagnosing problems.
In Windows, to always run with the console log, right-click on the Martus icon on your desktop, select Properties, select the Shortcut tab, delete the "w" from “javaw.exe” in the Target command line, and click OK. You can also create a copy of the default Martus desktop shortcut and make that change so the console will run when clicking on it, but please note that if you do this, the copied shortcut will not be removed when uninstalling Martus, which may be a security concern.
Another option is, instead of starting Martus by double-clicking the Martus icon on your desktop, choose Run from the Start menu and type the following text to launch Martus:
C:\Martus\bin\java.exe -jar C:\Martus\martus.jar
Save by hitting OK, and then double-click the updated shortcut to start Martus.
Note the console log messages you receive as you work in Martus, and e-mail those to firstname.lastname@example.org. To copy and paste the console messages into an email, please do the following:
To display additional information as Martus runs that will be helpful in diagnosing any problems in Mac OSX, you can open a Terminal window:
This will cause a new terminal to start which will contain the console output.
As long as the terminal is running, and troubleshooting or logging information from Martus will appear there. You can copy and paste the text from the terminal into an email to email@example.com.
In Linux, start Martus from the command-shell line, by typing
If the log doesn’t help us identify the problem, the issue may be caused by damaged fonts. Damaged fonts may prevent Martus from starting. To determine whether a damaged font is causing the problem, run Martus with the console log (see above), and check to see whether the word "font" appears in the console messages at all. If so, it is likely that damaged fonts are causing the problem. To fix this problem in Windows, copy all of the contents of C:\Windows\Fonts to a temporary location, then delete all of the contents from C:\Windows\Fonts. Then, copy all of the contents back into that folder from the temporary location. This process will reinstall all of the fonts and, in the process, detect any corrupt/damaged fonts. Once the damaged fonts have been identified, manually delete them from C:\Windows\Fonts.
For additional assistance, email firstname.lastname@example.org
To select the language in which you wish to use Martus see Change the Interface Language
A language pack allows you to install new and updated translations and documentation. Language Packs can contain updates to the Martus Client User Interface translation, the User Guide, Quick Start Guide, Readme file, and in-program help. To see current language packs offered for Martus see our webpage: https://martus.org/resources/documentation.html
Web browsers or word-processing applications may not display accents correctly in records or report files that you save from Martus. To ensure that accents appear when you open a Martus record or report in another application, specify UTF-8 (Unicode) font/character encoding. If you do not know how to do this in the application, please email email@example.com for assistance.
When you run the Arabic version of Martus in Windows XP, text in drop-down lists and/or column headers may not align correctly. To see the text as expected, set Windows to display user interface elements in "Windows classic style." From the Start menu, choose Settings > Control Panel. Then, double-click Display. In the Display Properties dialog box, click the Appearance tab, and choose Windows Classic Style from the Windows And Buttons menu.
In Martus 4.0 or later, Burmese fonts should display correctly in Windows without any extra steps required. If you notice any Burmese display issues, see the suggestions below, depending on which version of Martus and operating system you are running. If none of these suggestions fix the Burmese display issues, please email firstname.lastname@example.org.
For Martus 4.2 or later, if you notice that the fonts are not displaying correctly in the window title bars at the top of each screen, copy the Zawgyi-One font file from C:\Martus\lib\fonts\fallback to your Windows\Fonts folder, and do the following:
For Windows XP/Me
For Windows Vista/7
For Windows 98/2000
For Martus 4.2 or later, if you are running Martus in a language other than Burmese and want to type or view Burmese data in your record fields, choose Settings > System Preferences, and check Enable Zawgyi font to display Burmese. If you are running Martus in Burmese, it assumes you will be entering record data/text using the Zawgyi font, and the Enable Zawgyi font to display Burmese option should automatically be checked (if you uncheck it, the user interface will not display correctly in Burmese).
Some additional notes on using Burmese in Martus 4.2 or later:
If you are running Martus 4.2 or later in Burmese on Mac:
Note: If you get a message saying that the translation is out of date with the current version of Martus, check to see if there is a Martus Language Pack (Martus-bur.mlp) available at martus.org, and if there is, please download it and copy into your C:\Martus directory, and run Martus again.
In Martus 4.0 or later, Khmer fonts should display correctly in Windows without any extra steps required. If you notice that the fonts are not displaying correctly in the window title bars at the top of each screen, copy the KhmerOS font file from C:\Martus\lib\fonts\fallback to your Windows\Fonts folder, and follow the steps in e) below.
If you are running Martus 4.0 or later in Khmer on Mac and the fonts are not displaying correctly, you can find the KhmerOS font inside the Fonts folder of the Martus DMG (or zip file) – double-click on it to install.
When you start Martus, in the log in screen you will see a small language dropdown in the lower left-hand corner. This should now contain Khmer as an option. When you select it, Martus should begin displaying the Khmer translation. Please note that in the currently available Khmer translation of Martus some newer functionality will not be translated. Phrases which have been translated will display in Khmer. Phrases that have not been translated will display in English with brackets (i.e. <…>) around them. Translations that are in Khmer but not up-to-date with the current English Martus text will be marked with brackets around them as well, and if you see these in any screens you are using, we recommend switching to English so that you have the latest guidelines on how to use the software. This is especially important in help screens (e.g. customization, search) where new functionality may have been added and the old instructions may be misleading or incomplete.
If you notice that Khmer is not displaying correctly in the window title bars at the top of each screen, you should exit Martus, do the following steps, and then restart Martus.
For Windows XP/Me
For Windows Vista/7
For Windows 98/2000
Start Martus as usual. Pick Khmer from the language dropdown on the Martus SignIn screen. If you get a message saying that the translation is out of date with the current version of Martus, check to see if there is a Martus Language Pack (Martus-km.mlp) available at marus.org, and if there is, please download it and copy into your C:\Martus directory, and run Martus again.
In Martus 4.0 or later, Bengali/Bangla fonts should display correctly in Windows without any extra steps required. If you are running Martus 4.0 or later in Bengali/Bangla on Mac and the fonts are not displaying correctly, you can find the Rupali font inside the Fonts folder of the Martus DMG (or zip file) – double-click on it to install.
Benetech often gets the question: Can I get the Martus User Guide in a different language? The answers is yes. In fact, you probably already have multiple versions on your computer. When you install Martus, all the language versions of the user guide and quick start guide that are currently available are installed in your Martus\Docs directory. They are also available at martus.org, and you can visit this site to see whether new language versions are available. Additionally, there may be language packs available at that same page on Martus web site. A language pack can contain updated versions of the Martus user interface translation, the User Guide, the Quick Start Guide, and the Readme file (which describes the updates between Martus releases) in a particular language.
Ensure you have an active Internet connection, and that you’ve set up a server. Records are not listed as On Server until they have been successfully sent to the server. Records may also take up to an hour to send if you are sending a large attachment, or if the connection is slow. While Martus is sending the record, it displays a progress meter in the status bar at the bottom of the screen. Additionally, when you connect to a server, there may be a delay before the On Server column is populated.
Make sure you’re entering the correct username and password, especially if you changed the password recently. Your username and password are case-sensitive. Make sure you’re entering capital letters, as well as spaces and punctuation, exactly as you entered them when you created the username and password. Each time you enter an incorrect username or password, the system delays for a longer period before displaying the Martus SignIn dialog box again. Since Martus does not store your password anywhere, and it uses strong encryption, there is no way to get access to your account without your username and password unless you have performed a multi-file key backup.
You can access Martus only on a computer that contains your key file. Your username and password activate your key, which may not be present on your co-worker’s computer. There can be multiple accounts on a single computer, but your key must be available on that computer for you to access it. To access your account on your co-worker’s computer, click the Restore Account tab in the Martus SignIn dialog box, and then use your backup key file to create the account. And, though you can install your key on more than one computer at a time, remember that you need to update each key if you change your password, and that your data is only as secure as the least secure computer on which you have your account.
If you have set up your account on multiple computers, you can’t access your records from a different computer unless they were saved to the server and downloaded to the current computer. If you overwrite a record on the server from one computer, the version on the server will not match the version on the other computer because the server saves the last version of the record. To download the most recent record version from the backup server, you will need to delete any older versions from your computer. If you want to keep a backup copy of the older record, you can export the record before deleting it. If you delete a record from one computer and from the server, it will still be on the other computer. On that other computer, if you modify the record, it will re-upload it to the server, but if you never modify the record, it will never get re-upload.
Once you’ve versioned a record—whether or not you've sent it to the server, neither you nor anyone else can ever edit the original record again. However, if you have information to add to a versioned record, or need to make an important correction, you can create a new version of the record (see Version a record) and send it to a server. Both the original version and the new version will then be available on your computer and the server.
Delete the record from under all labels before emptying the Trash.
Yes, if you have a backup device large enough to hold all your data (e.g. CD, USB etc.). Copy the entire Martus folder onto your backup media. This folder contains the Martus application, the Java runtime environment, encrypted key files, configuration data, and records for all Martus accounts on the computer. For a minimal backup, copy only the MartusKeyPair.dat file and the Packets and Accounts folders from your account directory.
The Options dialog box lets you choose a language for the Martus software user interface. Martus has been translated into several languages. Visit https://www.martus.org to see which languages are currently available, including any language packs that have been added since the latest Martus release. If you are interested in translating Martus into another language, please contact us at email@example.com.
As you noticed, there are several languages available in the Language drop-down list when you create a record. That option specifies the language you use to enter the data into your record. You do not need to type the record in the same language used in your user interface.
Some suggestions for dealing with slow performance are below:
C:\Martus\bin\java.exe -Xms512m -Xmx1024m -jar C:\Martus\martus.jar
Save by hitting OK, and then double-click the updated shortcut to start Martus.
To resolve memory issues in Mac (if installed with a DMG), do the following:
This will allow Martus to get more memory than it does by default when installed, and will also turn on logging so that if there is a problem we can tell what it might be. The values of the memory switches (512 and 1024) are suggestions, but the best value is dependent on your computer's setup, so you may be able to optimize this setting. For a more specific recommendation, send information about your computer (how much memory or RAM is installed, how much swap or page file space is available, etc.) to firstname.lastname@example.org. In Windows, you can find this information by choosing Start > Programs > Accessories > System Tools > System Information. In Mac, go to the Apple menu > About this Mac > More info… > System report… > Hardware (this is the Hardware Overview). If the pagefile is small, you may want to try to increase it.
Martus always installs a shortcut in your Martus directory, which you can use to start Martus. Or, use one of the following methods, depending on your operating system:
To start Martus in Windows, open a DOS prompt, change to the Martus directory, and type:
C:\Martus\bin\javaw.exe -jar C:\Martus\martus.jar
In Mac OS:
In Linux, start Martus from the command-shell line, by typing:
See Linux portion of section Getting Started for examples.
Depending on your computer system, there may be a delay of several seconds between the time you sign in and the Martus main page and workspace appear. Exactly how long it takes depends on the speed of your computer.
Follow instructions to open a "console log" that displays additional information as Martus runs. This information is helpful to us in diagnosing problems. Note the console log messages you receive as you work in Martus, and e-mail those to email@example.com.
If the log doesn’t help us identify the problem, the issue may be caused by damaged fonts.
For additional assistance, email firstname.lastname@example.org.
No, currently there are no limits for the amount of data, the number of records, or the size of attachments you can send to a Martus Server. However, it's possible that there may be limits on certain servers in the future. If you send very large attachments (e.g. video) to the server just be aware that it will take longer than sending smaller amounts of data.
Yes. In fact, you probably already have multiple versions on your computer. When you install Martus, all the language versions of the user guide and quick start guide that are currently available are installed in your Martus\Docs directory. For more information see Languages
If Martus reports that the server isn’t available or that you can’t connect, first try to “ping” the server (which tells you what your connectivity is like to this server). To ping the server, open a command prompt window in Windows (or a Terminal window in Mac) and type:
(where server-ip-address is the same address you entered when you set up the server), and then press Return.
Then, try to “tracert” the server (which will tell you what the route is between your computer and the server.) To tracert the server, in the command prompt window in Windows (or the Terminal window in Mac), type:
and then press Return.
Email the results of the ping and the tracert that appear on your computer to email@example.com. Be sure to mention that you can’t connect to the server through Martus and tell us the date and time of day that you tried (please also include your time zone.) We’ll determine the nature of the problem and work with the server administrator to resolve it.
No. You can install Martus over an existing version of the software. The installer will notify you that an older version exists. Click Yes to upgrade Martus without losing any of your data, including records, account information, server configurations, or passwords. For more information, see Upgrading Martus.
When you first insert a USB (“thumb drive”), the operating system assigns it a drive letter; each drive is assigned a different drive letter. However, Martus expects to find each USB in the same drive. Before backing up your keypair to USB drives, reassign the drive letter for each drive so that they are all the same.
To reassign the drive letter in Windows:
If you are using a Mac, and can’t find your USB location, look under the Volumes folder in the main Mac hard drive display.
The problem may be occurring because of incompatible versions of Java installed on your machine.
To check which version of Java you are running, open a Terminal window and type:
and hit Return/Enter.
As of Martus 4.5, Martus should be run with Java 1.8 (sometimes called Java8) – see the Mac requirements section for more on this.
See earlier versions of the Martus User Guide (at https://www.martus.org) for instructions for earlier releases of Martus.
The normal Linux installation instructions only allow Martus to be used by the user who installed it. You can also install Martus on a Linux computer such that any user on that computer will be able to run it. If you do this, any user should be able to run Martus by simply typing "martus" on the command line, from any directory. Each user can also create a launcher or alias to the /usr/bin/martus script. If you install Martus to be available to all users, the program can be more secure (against tampering), but it will be much more difficult to erase quickly, and the "wipeout" feature will not delete the application.
Note that each user's data will still be stored separately, within the user's home directory: ~/.Martus/
The installation steps will be the same as in the Linux portion of Getting Started, but:
sudo mkdir -p /usr/share/java/martus
sudo cp martus /usr/bin
Go to Account > Account Information. Martus will bring up a screen displaying various account information, including a public code composed of sets of 4-digit numbers. Please send this public code information to firstname.lastname@example.org, letting us know that it is a test account.
In Windows, if you click within the console log, it can cause Windows to suspend that process. When this happens, you will see the word "Select" at the beginning of the console Window Title, or title bar. To "unselect" the console, right-click in the body of the console – this should cause the "Select" message in the Window Title to disappear. To prevent this from happening in the future, right-click in the title bar of the console, select Properties, select the Options tab, and uncheck "Quick Edit Mode." When you hit OK, pick "Modify shortcut that started this window."
When you change customizations, Martus will do its best to update the old formatted data to the new customization if you create a new version of a record with the old customization. If you add completely new fields but don’t change any of the old fields, the new version of the record will have all the old fields filled in as they were in the previous version, and the new fields will be blank and you can fill them in. If you delete fields, the new version of the record will not contain those fields, but you can go back to see the deleted fields in the previous version if it was a versioned record instead of a saved record (by hitting the Record Details button in the bottom section of the record), and copy any info from the old version into a different field in the new one if desired.
You have to be very careful if you make changes to the customization definitions of old fields. If you keep the same tag and label, but change the type of field, Martus may be able to transfer the old data into the new field type, but not in all cases. For example,
DROPDOWN and GRID fields are subject to additional rules regarding the modification of dropdown options/values and grid columns. If you
If you change fields and lose old data in the new version as a result, please note that you can go back to see the deleted data in the previous version if it was a versioned record instead of a saved record (by hitting the Record Details button in the bottom section of the record), and copy any info from the old version into a different field in the new one if desired.
In this release, if you want to change the number of levels in a “Reusable Choices” dropdown field when updating a customization, you should also change the field tag and/or label so that they are more easily distinguished from each other in searching and reporting. If you do not, the search/report results may be confusing since fields with the same label/tag will be treated differently due to them having a different number of levels.
If you update the default value for a field, please note that the new default value will only be applied when a new record is created, not when a new version of a record is created, so that whatever the value of the field in the previous version was will remain the same and not be overwritten.
In general if you are making changes to your customization, please make sure to test the transferring of data using a test record.
When attachments are stored in Martus records they are encrypted, so that nobody except you can read them. However, when you open an attachment in a Martus record so that another program loads it (e.g. a document in Microsoft Word), your computer Operating System creates a temporary version of the file that is not encrypted, and that file is usually saved to your hard drive, in the standard Temp directory for your Operating System (e.g. “C:\Documents and Settings\your-user-name\Local Settings\Temp” in Windows XP) or “/tmp” for Mac and Linux. If you are concerned about anyone seeing these files, you should at least delete them and empty your Recycled Bin (this will remove them from view of most users, but sophisticated users could still find the content with some work), but best of all would be to use an electronic file “shredder” (E.g. http://www.fileshredder.org/ for Windows) for any Martus files in the Temp directory. The Martus files in the temp directory will be given names based on the attachment name in Martus. For example, a file named Interview.doc in Martus might appear as something like Interview23424.doc in the Temp directory. This may not work for all Operating Systems, but if you cannot find the Temp directory, you can try opening the file in Martus, and then saving it with a different name so that you can see where the current version of the file is being stored.
You can change the Martus time-out length when there is no activity to be however long you want, instead of always timing out at the default of 10 minutes. In addition to providing extra security if you are working in a public place or on a shared computer and want to shorten the timeout to only a few minutes, you can also improve the performance of long operations (such as retrieval of records from the server) by setting the timeout to a longer amount of time if you are working in a secure location. Different time-out lengths are allowed by setting a parameter in the command line used to run Martus. The parameter is "--timeout-minutes=X" where X can be any number of minutes. For example, to set the timeout length for Martus running on your computer in Windows to always be 5 minutes for a higher level of security, change the command line in the desktop shortcut (right-click, and choose Properties) to the following:
C:\Martus\bin\java.exe -jar C:\Martus\martus.jar --timeout-minutes=5
For a Mac DMG install, to set the timeout length for Martus to always be 5 minutes for a higher level of security, do the following:
You should see the new timeout length in the Martus console.
If there is a translation of an older version of Martus in your language that you can choose to use, it usually means that most of the Martus screens will be in your language, but some newer functionality will not be translated. The more recent the version number of your translation compared to the current version number of the Martus release, the more of the Martus screens will be up to date in your language. Translations that are in your language but not up-to-date with the current English Martus text will be marked with brackets (i.e. <…>) around them, and if you see these in any screens you are using, we recommend switching to English so that you have the latest guidelines on how to use the software. This is especially important in help screens (e.g. customization, search) where new functionality may have been added and the old instructions may be misleading or incomplete.
The current version of Martus includes Java8 in Windows while earlier versions included Java6. You can run those earlier versions of Martus with Java8 (also sometimes called Java 1.8), if you need to (E.g. to display certain fonts or to help if you are receiving import errors with very large files). Instructions to do this in Windows are as follows:
"C:\Program Files\Java\jre8\bin\java.exe" -jar C:\Martus\martus.jar
or equivalent based on where you installed Java8:
"C:\where-you-installed-java\jre8\bin\java.exe" -jar C:\Martus\martus.jar
On Mac, if you have multiple versions of Java installed, you will need to launch the Java Preferences dialogue to change the version of Java that is used. To locate it, hit Command-Space to bring up the "Spotlight" search, and type Java Preferences. Once it is open, you will see two sets of configurations, one for Java applet plugins and another for Java applications. If you wish to change the version of Java Martus uses by default, select the new version using the dialogue instructions, then close out of the Java Preferences screen.
There are several reasons that Martus might not be finding a record that you expect, or may be finding records that you didn’t expect.
For more information about finding records in Martus see Search for specific records.
If you pick a Reusable Choices dropdown field to search on, the values that are displayed as the criteria dropdown list options are the labels for each list entry, but the codes you defined determine how many entries there will be in the search dropdown list. So if you have different reusable choices codes with the same label in different record customizations in your account, the labels will show up twice in search dropdown lists (i.e. if you used label1 for both code1 and code2, you will see 2 entries in the search dropdown that looks like "label1" and if you want your search to be on records that have that label, regardless of which code the customization had for the label, you will need to do a “or” search on both labels). And if you have the same reusable choices code with different labels in different record customizations in your account, the search dropdown list for that code will show both values separated by a semicolon (i.e. if you used code1 for both label1 and label2, you will see an entry in the search dropdown that looks like "label1; label2" and your search will be on records that have either of those labels).
If you have fields in different records or from different customizations that are exactly the same, Martus will combine them in any Search and Report field lists. And while Martus warns you about duplicate labels where you are creating a new record customization, it is possible that over time, you may have records with different customizations that ended up with the same labels (e.g. maybe you changed a text field to a dropdown field but kept the same label). In these cases, Martus will try to help you figure out the difference between the fields by displaying what the field type and tag are in the field selection lists. Also, if you have fields with the same tag but different labels and/or field types, Martus may use the tag and field type to try and determine when different fields were meant to be the same. So we encourage you to make your field tags and labels in a customization clearly related to each other to avoid any confusion.
In Mac OS, the Martus data directory (and some other program directories) are hidden by default. These directories are not viewable using the Finder application, and are prefaced with a "." (e.g. ".Martus"). Martus saves some files Contact account files directly to the Martus directory by default (though you can also choose to save them elsewhere on your computer). In order to access these files, you will need to set your computer preferences to "show" these hidden folders. To do so, follow these steps:
defaults write com.apple.finder AppleShowAllFiles TRUE
and hit Enter.
and hit Enter/Return.)
Please see the Martus website for web and video tutorials on how to use Martus, including installation and troubleshooting for Windows and Mac. You can find these at https://martus.org/resources/trainingmaterials.html.
Some users have noticed this issue when running Martus on Windows 7. Please try the following steps to resolve it:
The Onion Router, or Tor), is software and an open network that provides anonymity and privacy protection over the internet. Tor routes an internet user’s traffic through a global network of relays in such a way as to obscure both the origin and the destination of the traffic. By bouncing your communications around a distributed network all around the world, Tor helps defend against a form of network surveillance known as traffic analysis. It will make sending records harder to track, but also much slower.
WARNING: Before using Tor, please read the full list of warnings available at https://www.torproject.org/download/download#warning. If you have any questions about what Tor does or does not do, or any other Tor-specific questions, email the Tor support team at email@example.com. (For questions about Martus and Tor, email the Martus support team at firstname.lastname@example.org).
You can run Martus with Tor by toggling the Tor button in the Martus main taskbar On / Off.
Users operating in particularly oppressive or antagonistic online contexts may be interested in tools that better preserve their privacy, circumvent censorship and completely bypass a compromised hard drive.
One such tool is Tails (The Amnesic Incognito Live System, https://tails.boum.org/) a free, open source bootable LiveUSB or LiveDVD that offers advanced security and privacy features by default. It allows users to boot from virtually any computer using a previously-configured DVD or USB stick, bypassing that computer’s internal hard drive. Tails anonymizes a user's internet activity by routing all connections through the Tor network, leaves no trace on the computer being used, and provides the latest open source cryptographic tools, allowing users to encrypt their emails, chats and files. Its file system is read-only, so is unaffected by Trojans and other malware.
For more information about Tails, please see the About page on theTails website.
Tails is not necessary for all Martus users, but may be a useful solution for users who:
Martus can be installed on Tails and Benetech can provide insturctions, however these are currently being updated as Tails is supgraded. If you are interested in receiving these instructions or further support for using Martus on Tails, please email email@example.com
On OSX Mountain Lion (10.8) and later, the default security settings sometimes only allow users to run applications that either have been downloaded directly from the Mac App Store, or have been published by one of Apple’s identified developers. The current version of Martus does not meet those criteria, so you can get this warning if you double-click on the app to run it.
Instead of double-clicking to run the Martus app, right-click and choose “Open”. You will still get a warning screen, but you can choose to open the Martus app to run it.