for version 0.5

<<<<<<< HEAD

for version 0.4.2

# Getting Started with RoboJournal

## Sections

## First-Run Overview

RoboJournal stores its settings in configuration files. Instead of sharing the same settings for all users on the system, each user has a .robojournal folder containing a robojournal.ini configuration file in his or her home directory. This design allows each user to customize the same installation of RoboJournal to his or her own specifications.

RoboJournal automatically initiates first-run mode if it can't find a valid configuration file when it starts. This is guaranteed to happen the first time you use RoboJournal after installing it. The purpose of first-run mode is to establish the parameters used to govern RoboJournal's behavior. These parameters are written to a configuration file immediately after you have finished using the first-run tool.

You can force RoboJournal to reconfigure itself by deleting your current configuration file. This action triggers first-run mode the next time you start the program. You can also open your configuration file in a text editor (like Vim or Notepad) and edit it manually. Direct editing is only recommended if you need to make minor changes since it is easy to accidentally break your configuration file. If you already have a pre-existing configuration file, you can skip the first-run process altogether by placing that configuration file in your home directory's .robojournal folder; RoboJournal will detect and use that configuration file instead of initiating first-run mode.

FYI: Older versions of RoboJournal (0.1–0.3) used a different configuration file called robojournal.cfg. This old configuration format has been officially deprecated. Newer versions of RoboJournal (0.4 and later) initiate first-run mode the first time you use them even if a robojournal.cfg file from an older version is already present.

The Welcome to RoboJournal dialog is displayed whenever RoboJournal initiates first-run mode:

Figure 1: The Welcome to RoboJournal dialog.

During first-run, you must decide whether you want to create a new (blank) journal or configure RoboJournal to use an existing journal database. Select the desired option on the Welcome to RoboJournal window and then click the OK button to continue.

Alternatively, you can abort the configuration process by clicking the Cancel button. However, RoboJournal will continue to initiate first-run mode each time you use it until a configuration file has been created.

## Creating a New Journal Database

The Journal Creator consists of a tabbed interface. Each tab must be completed in full before a journal can be created. Completing this dialog requires root-level access to the MySQL installation on the host you specify. Without root access, you will not be able to create any journals.

The Set this new journal as my default checkbox is always checked (and locked) during first-run. If you run the Journal Creator again at a later time, this checkbox (then unchecked and unlocked) gives you the option to replace the current default with the brand-new journal.

Complete the following procedure to create a brand-new, empty journal:

1. Select the Create a new journal database option on the Welcome to RoboJournal dialog and click the OK button. The Journal Creator dialog is displayed: Figure 2: Launching the Journal Creator during first-run.
2. Click the 2. Basic Settings tab. The fields that govern essential parameters for the new journal are displayed:Figure 3: Journal Creator — Basic Settings tab.
3. Enter a name for this journal database into the Journal name field. This name must be unique (no other database with the same name should exist on the indicated host). Short names are best; use underscores instead of spaces to separate words.
4. Enter the host for this journal into the Journal host field (if necessary). The default value of "localhost" is used if this field is left blank. Localhost (also known as "127.0.0.1") refers to the current machine that RoboJournal is running on. If you intend to store RoboJournal and the database on the same machine, leave the Journal host field blank. Otherwise, enter the domain name or IP address of the machine on which the journal should be stored (that machine must have a working MySQL server process).
5. Specify a username to associate with this journal and enter it into the Username field. You may not use "root" for the username!
6. Choose a password to associate with the username you specified in the previous step. Enter this password in the Password and Repeat fields. The contents of the Password and Repeat fields are always obscured for security purposes but the password indicator text notifies you when both passwords match. When both passwords are identical, the OK button for the Journal Creator is unlocked.
7. Switch to the 3. Authentication tab by clicking on it. The authentication-related options are displayed:Figure 4: Journal Creator — Authentication tab.
8. Enter the Root password for the host you specified in the Journal Host field on the 2. Basic Settings tab. The contents of the Root password field are always obscured for security reasons.
9. RoboJournal automatically sets a value of "3306" for the Port field; this is the standard port for MySQL servers. Make sure this value is correct for your particular situation and change it if necessary.
10. Click the OK button on the Journal Creator dialog window. A confirmation dialog is displayed if the journal creation process was successful.
    FYI: The next two steps are displayed only if RoboJournal is in first-run mode. Otherwise, RoboJournal preserves the user's full name and gender settings from the current configuration.
11. A text input dialog is displayed. Enter your name (as you prefer it) and click the OK button. You may click the Cancel button if you wish to skip this step.Figure 5: This value sets the user's full name in the configuration file.
12. A gender selection dialog is displayed. Select your gender by clicking the appropriate button.Figure 6: The gender selection dialog determines which avatar icon is used while a connection is active.

RoboJournal is now successfully configured. For more information on how to use core RoboJournal functionality, refer to the RoboJournal Fundamentals documentation.

## Assigning Permissions to a Database

You can use the Journal Selector to locate databases that have been restored from SQL dump files or migrated from other systems. Journals that you have created with your own user account (and have never been migrated or restored) can be located with relative ease. On the other hand, journals that have been imported from other sources or restored from a backup usually require some modifications before RoboJournal can even locate them.

In the same manner, remote journal databases usually require permission changes before you can access them from your computer (even if the remote database has never been restored from a backup or migrated from a different server). This is a deliberate security measure intended to reduce the likelihood of unauthorized remote tampering by restricting access to a few "whitelisted" users while blocking all others. All permission changes to a remote database require root-level access privileges and must be performed on the same machine where the database you wish to use is stored. To make the changes, you must either access the machine directly (if possible) or connect to it via a remote access method like SSH or VNC.

### MySQL Procedure

Restored databases are associated with the "root" user account by default and are therefore inaccessible to regular users. You must make some changes to the MySQL configuration in order to make a restored or migrated database easy to use with RoboJournal. This process requires root-level access to the MySQL console.

In the following procedure, assume that "sample_journal" represents an imported database while "john_doe" represents the user account you intend to associate the database with (and "123" is the password associated with the john_doe account). You must obviously change these values to those appropriate to your particular situation in order for this procedure to work properly in a real-world context:

1. Gain access (physically or otherwise) to the machine that contains the journal you wish to use.
2. Log in to the MySQL command line as root. The exact procedure varies by operating system:
   - On Linux, open a terminal and type mysql -u root -p and press Enter.
   - On Windows, click the Start Menu and select All Programs » MySQL » MySQL Server 5.5 » MySQL 5.5 Command Line Client (the "5.5" may vary depending on which version you have installed but the location is likely the same).
3. Type the root password when prompted to do so (the password is hidden for security purposes as you type it). Press Enter.
4. A mysql> command prompt is displayed if the login was successful.
5. Create a user account for yourself (if necessary) with the with the CREATE USER command. You may skip this step if your user account already exists.
   - Otherwise, type CREATE USER 'john_doe'@'localhost' IDENTIFIED BY '123'; and press Enter (don't forget to substitute the real username, host, and password in the query). MySQL displays Query OK, 0 Rows Affected if the command was successful.
6. Use the GRANT command to give your user account (in this case, john_doe) permission to use the database you imported; type GRANT INSERT,DELETE,UPDATE,SELECT ON sample_journal.entries TO 'john_doe'@'localhost'; and press Enter (don't forget to substitute the real journal name, username, and host in the query). MySQL displays Query OK, 0 Rows Affected if the command was successful.
   FYI: You should only grant permissions that are absolutely necessary (i.e. INSERT, DELETE, UPDATE, and SELECT) because additional permissions will not make your account work any better and can actually be dangerous to other databases.
7. Type exit and press Enter to disconnect from the MySQL command line.

MySQL requires you to use a GRANT query to give yourself permission to view and/or modify a remote journal database on your workstation. For instance, assume that a journal database called "test" is stored on 192.168.2.1 and you wish to access it through the "john_doe" user account on your workstation at 192.168.2.3. You would log in (as root) to the MySQL command interface on 192.168.2.1 and run, GRANT INSERT,DELETE,UPDATE,SELECT ON test.entries TO 'john_doe'@'192.168.2.3'; to give yourself permission to access the journal.

You are ready to begin the journal selection procedure once you have assigned the correct permissions to the database you wish to set as your default.

## Connecting to an Existing Journal Database

RoboJournal's journal selection tool provides an easy way to select the default journal during the first-run session. This tool allows you to specify the username and password for a pre-existing account on a host machine (local or remote). Once you have provided this information, RoboJournal displays all databases associated with that specific user account.

In order to use this tool successfully, you must know the correct username and password for the account you wish to access since RoboJournal currently has no way of retrieving a full list of accounts from the host. Furthermore, this tool only lists databases that are associated with the user account you provide (all others are ignored). Before you use the Journal Selector, you must assign the correct user permissions to the database you wish to use or RoboJournal will be unable to find it.

1. Click to select the Connect to an existing journal database option on the Welcome to RoboJournal dialog and click the OK button. Figure 7: The Journal Selector is launched via the Welcome to RoboJournal dialog.
2. The Journal Selector window is displayed. Change the Host and Port values if necessary (you must uncheck the Use default host and port box to make the Host and Port fields writable).Figure 8: The Host and Port fields are automatically populated with the most common default values.
3. Enter the appropriate username and password into their respective fields (indicated within the red circle in Figure 9). These values should belong to the account you wish to use as your own (do not use root). The contents of the Password field are always obscured for security reasons. Figure 9: Fill in the indicated fields to display a list of journals associated with a specific account.
4. Click the Search for Journals button.
5. A list of journals associated with the user account you provided is displayed in the large open area on the left:Figure 10: The Journal Selector displays all databases associated with a specific user account.
6. Select the journal you wish to use by clicking on its node in the hierarchy. Once a journal has been selected, the OK button on the Journal Selector window is unlocked (as shown in Figure 11).
7. Click the OK button to continue.Figure 11: The OK button unlocks once you have selected an entry.
   FYI: The next two steps are displayed only if RoboJournal is in first-run mode. Otherwise, RoboJournal preserves the user's full name and gender settings from the current configuration.
   If RoboJournal is not in first-run mode, you are asked to confirm your decision to replace your current default journal. Your previous settings are not changed at all if you decide to abort.
8. A text input dialog is displayed. Enter your name (as you prefer it) and click the OK button. You may click the Cancel button if you wish to skip this step.Figure 12: This value sets the user's full name in the configuration file.
9. A gender selection dialog is displayed. Select your gender by clicking the appropriate button.Figure 13: The gender selection dialog determines which avatar icon is used while a connection is active.

RoboJournal is now successfully configured. For more information on how to use core RoboJournal functionality, refer to the RoboJournal Fundamentals documentation.

Copyright © 2013 by Will Kraft. All parts of the RoboJournal Documentation are covered by the terms of the GNU Free Documentation License.

=======

# Getting Started with RoboJournal

## Sections

## First-Run Overview

RoboJournal stores its settings in configuration files. Instead of sharing the same settings for all users on the system, each user has a .robojournal folder containing a robojournal.ini configuration file in his or her home directory. This design allows each user to customize the same installation of RoboJournal to his or her own specifications.

RoboJournal automatically initiates first-run mode if it can't find a valid configuration file when it starts. This is guaranteed to happen the first time you use RoboJournal after installing it. The purpose of first-run mode is to establish the parameters used to govern RoboJournal's behavior. These parameters are written to a configuration file immediately after you have finished using the first-run tool.

You can force RoboJournal to reconfigure itself by deleting your current configuration file. This action triggers first-run mode the next time you start the program. You can also open your configuration file in a text editor (like Vim or Notepad) and edit it manually. Direct editing is only recommended if you need to make minor changes since it is easy to accidentally break your configuration file. If you already have a pre-existing configuration file, you can skip the first-run process altogether by placing that configuration file in your home directory's .robojournal folder; RoboJournal will detect and use that configuration file instead of initiating first-run mode.

FYI: Older versions of RoboJournal (0.1—0.3) used a different configuration file called robojournal.cfg. This old configuration format has been officially deprecated. Newer versions of RoboJournal (0.4 and later) initiate first-run mode the first time you use them even if a robojournal.cfg file from an older version is already present.

The Welcome to RoboJournal dialog is displayed whenever RoboJournal initiates first-run mode:

Figure 1: The Welcome to RoboJournal dialog.

During first-run, you must decide whether you want to create a new (blank) journal or configure RoboJournal to use an existing journal database. Select the desired option on the Welcome to RoboJournal window and then click the Proceed button to continue.

If desired, you can click the Help button to display the RoboJournal Documentation in Qt Assistant. This feature was added in Robojournal 0.5 to resolve the problem of the documentation not being available until after configuration has been completed.

Alternatively, you can abort the configuration process by clicking the Cancel button. However, RoboJournal will continue to start in first-run mode each time you run it until you create a configuration file.

## Creating a New Journal Database

The Journal Creator has been completely redesigned for RoboJournal 0.5. It now consists of a highly modular "paged" design, similar to the RoboJournal Preferences window that was introduced in RoboJournal 0.4. The Journal Creator can be directly accessed during first-run or by clicking the Journal Creator item in the Database drop-down list on the RoboJournal main window.

Select the Create a new journal database option on the Welcome to RoboJournal dialog and click the Proceed button to launch the Journal Creator. Alternatively, you can select the Journal Creator option from the main window's Database drop-down list:Figure 2: The Journal Creator can be invoked from the Welcome to RoboJournal window or the main window's Database drop-down menu.

In either case, the Journal Creator window is displayed:Figure 3: Journal Creator Overview page.

The Set the new journal as the default checkbox is always checked (and locked) during first-run. If you run the Journal Creator again at a later time, this checkbox (then unchecked and unlocked) gives you the option to replace the current default with the brand-new journal. The Journal Creator always shows the Overview page by default.

### Creating a MySQL-Based Journal

RoboJournal requires root permissions to create a new MySQL-based journal database. Be sure you have root-level database access before completing the following steps:

1. Once the Journal Creator window is open, click the MySQL/MariaDB Journal option in the menu on the left side of the window. The MySQL Journal page is displayed:Figure 4: The Journal Creator populates several fields automatically based on your operating system settings.
2. RoboJournal automatically populates the Journal name and Username fields with default values based on your system-level username (which you log in under on Windows or Linux). The default values are designed to be adequate for most users but you can change them to something else if necessary.
3. Make up a password at least seven characters in length to go with your new username and enter it into the Password and Repeat fields. You should manually type your password into both fields to eliminate the possibility of typing mistakes instead of copy-and-pasting. RoboJournal unlocks the OK button once both password fields match.
   Once both password fields match, the Journal Creator assigns a strength rating to your password based on certain criteria. The strength ratings range from 0 (extremely weak) to 100 (extremely secure). Generally, a strength rating of at least 75/100 means your password is strong enough to resist most attempts to crack it. Figure 5: The Password strength meter provides a visual indicator of password quality and resilience.
   FYI: Password strength is calculated according to length and diversity. A strong (>50/100) password contains a random mixture of glyphs (upper and lowercase letters, integers, and symbols) and no dictionary words. RoboJournal adds points to the score for long passwords and the inclusion of all glyph varieties but docks points for adjacent glyphs of the same type (two or more letters, numbers, or symbols in a row) and repeating glyphs (two or more instances of the same character). If you need help creating strong passwords, tools like Strong Password Generator or Randompass can produce an unlimited number of suitable glyph combinations.
4. Adjust the values in the Hostname and Port fields if necessary. Leaving these fields blank causes RoboJournal to use the built-in placeholder values ("localhost" for Hostname and "3306" for Port).
5. Enter the Root password for the server you specified in the Hostname field.
6. Click the OK button on the Journal Creator window. Once you have done so, RoboJournal attempts to create the new journal with the parameters you specified: Figure 6: The MySQL page with all fields completely filled in.
   FYI: If your password's strength is less than 50/100 and confirmation dialogs are enabled, RoboJournal issues a warning and requires you to verify your decision to use a weak password.
7. If the journal was successfully created, RoboJournal asks you if you want to add the new journal to your list of favorites. If you select Yes, the journal is added at this time. RoboJournal simply appends the new journal to the List of Known Journals if you choose No. To prevent your list of favorites from becoming too cluttered, you should only add journals you intend to use on a regular basis.
   RoboJournal can create journals on remote hosts in this manner only if you have enabled MySQL remote root access. If you have done so, RoboJournal attempts to create the journal and then sets the appropriate permissions that are required to access the journal from your current computer. However, the permission granting process is not completely reliable when automated so it is sometimes necessary to do it by hand.
   FYI: The next two steps are displayed only if RoboJournal is in first-run mode. Otherwise, RoboJournal preserves the user's full name and gender settings from the current configuration.
8. A text input dialog is displayed. Enter your name (as you prefer it) and click the OK button. You can click the Cancel button if you wish to skip this step. Skipping this step causes RoboJournal to use your username (instead of your full name) as an identifier in the Entry Output Pane's header area.Figure 5: This value sets the user's full name in the configuration file.
9. A gender selection dialog is displayed. Select your gender by clicking the appropriate button.Figure 6: The gender selection dialog determines which avatar icon is used while a connection is active.

Once the configuration file has been created and there is at least one journal on the host, RoboJournal ceases to operate in first-run mode and is now ready to be used normally. For more information on how to use core RoboJournal functionality, refer to the RoboJournal Fundamentals documentation.

## Assigning Permissions to a Database

You can use the Journal Selector to locate databases that have been restored from SQL dump files or migrated from other systems. Journals that you have created with your own user account (and have never been migrated or restored) can be located with relative ease. On the other hand, journals that have been imported from other sources or restored from a backup usually require some modifications before RoboJournal can even locate them.

In the same manner, remote journal databases usually require permission changes before you can access them from your computer (even if the remote database has never been restored from a backup or migrated from a different server). This is a deliberate security measure intended to reduce the likelihood of unauthorized remote tampering by restricting access to a few "whitelisted" users while blocking all others.

### Assign Permissions Extension

RoboJournal 0.5 introduces the Assign Permissions extension to the Journal Selector. This new feature greatly simplifies the process of associating an existing database with your own user account and is intended to be a replacement for the old MySQL Manual Procedure (which required you to access the MySQL command line interface directly). The Assign Permissions extension is also the easiest way to create a user account for yourself if one does not already exist on the host server.

You need root-level database access in order to change database permissions and create user accounts, so make sure you have all required clearance before you begin. The Assign Permissions extension should be used whenever it is necessary to grant permissions to a database. For instance, migrated or restored databases are usually owned by the root user; all other user accounts (and therefore RoboJournal) are unable to access or modify such databases until the necessary access permissions have been granted.

The Assign Permissions extension is initiated by clicking the Assign Permissions button on the Journal Selector window:Figure 7: The Assign Permissions window is accessed through the Journal Selector.

The Assign Permissions window is displayed:Figure 8: The Assign Permissions window immediately after launch.

Since it is an extension to the Journal Selector (rather than being an independent module), the Assign Permissions extension inherits its database mode from the current setting of the Journal Selector's Database field. For instance, the Assign Permissions extension starts in MySQL mode if the Journal Creator is configured to work with MySQL databases at the time. The current mode is displayed in the Assign Permissions window title bar (i.e. "Assign Permissions - MySQL"). It is impossible to switch database modes without first changing the current backend on the Journal Selector window and then re-initializing the Assign Permissions extension.

Certain fields on the Assign Permissions window can never be cleared. Instead, they use placeholder text as default values that represent the most common/most likely values for the field in question in typical scenarios. Placeholder text is displayed when the affected fields would otherwise be empty. Placeholder text is differentiated from standard text by its lighter color (gray instead of black).

1. Change the contents of the Hostname and Port fields in the Database Settings group (if necessary). The Hostname field refers to the server where the database you wish to use is stored while Port determines which connection port RoboJournal should use during database transactions. The port you should use depends on how your server is configured but it is usually "3306" on MySQL servers. Leaving these fields blank causes RoboJournal to use the placeholder values for that particular database type.
2. Enter the Root password for the database server located at Hostname (the contents of the Root password field are obscured for security reasons).
   FYI: As a security precaution, MySQL forbids remote root logins (i.e. using Computer #1 to log into the root account on Computer #2) unless you grant the necessary permissions beforehand. Consult the MySQL Manual Procedure for details.
3. Click the Scan button to run a search. Since this connection is through the root-level account, every database on the host is added to the Select database drop-down list. This action causes the Grant Settings group to unlock since it is now time to bind one of these databases to a regular user account. The Scan button locks once the Select database list has been populated.
4. Select the database you wish to associate with your account from the Select database drop-down list:Figure 9: Logging in through the Root account allows you to access every database on the server.
5. The next three steps determine which user account the selected database should be bound to. If you already have an account, enter your username into the Username field in the Grant Settings group. To create a new user account, make up a username and enter it into the Username field at this time.
6. Enter the password that goes with your username into the Password field (the contents of the Password field are obscured for security reasons). If you wish to create a new user account, make up a password and enter it into the Password field now.
7. Enter the correct hostname for your user account into the User host field (if necessary). Leaving the field blank causes RoboJournal to use the placeholder value ("localhost"). The User host value is only important if you intend to access your journal from a remote location. If this is the case, enter the hostname of the remote terminal into the User host field. For instance, you should enter "192.168.2.4" into the field if your journal database is stored on 192.168.2.3 and you wish to access it from the computer at 192.168.2.4. Type "%" in the User host field if you need to be able to access the database from any host (not recommended).
8. Click the OK button to continue.Figure 10: The OK button is unlocked once you have selected a journal to associate with your user account.

If the operation was successful, the database you selected is now associated with your user account. From now on, it should be included in your list of databases that is displayed whenever you log in with your account credentials on the Journal Selector window. The database you just associated with your user account will be added to your list of known databases the next time you log in or search for databases with the Journal Selector tool.

The Create user account if it does not exist checkbox instructs RoboJournal to create a new user account for you with the username and password you provided if an account matching those credentials does not already exist. This option does not alter an existing account's username or password; if your account exists, the current database is simply added to the list of those associated with you, thereby allowing you to access it through RoboJournal.

### MySQL Manual Procedure (deprecated)

FYI: This section is preserved in the documentation for legacy/failsafe purposes only. Most users should use the Assign Permissions extension instead since that new feature accomplishes the same task much more easily.

All permission changes to a remote database require root-level access privileges and must be performed on the same machine where the database you wish to use is stored. To make the changes, you must either access the machine directly (if possible) or connect to it via a remote access method like SSH or VNC. Restored databases are associated with the "root" user account by default and are therefore inaccessible to regular users. You must make some changes to the MySQL configuration in order to make a restored or migrated database easy to use with RoboJournal. This process requires root-level access to the MySQL console.

In the following procedure, assume that "sample_journal" represents an imported database while "john_doe" represents the user account you intend to associate the database with (and "123" is the password associated with the john_doe account). You must obviously change these values to those appropriate to your particular situation in order for this procedure to work properly in a real-world context:

1. Gain access (physically or otherwise) to the machine that contains the journal you wish to use.
2. Log in to the MySQL command line as root. The exact procedure varies by operating system:
   - On Linux, open a terminal and type mysql -u root -p and press Enter.
   - On Windows, click the Start Menu and select All Programs → MySQL → MySQL Server 5.5 → MySQL 5.5 Command Line Client (the "5.5" may vary depending on which version you have installed but the location is likely the same).
3. Type the root password when prompted to do so (the password is hidden for security purposes as you type it). Press Enter.
4. A mysql> command prompt is displayed if the login was successful.
5. Create a user account for yourself (if necessary) with the with the CREATE USER command. You may skip this step if your user account already exists.
   - Otherwise, type CREATE USER 'john_doe'@'localhost' IDENTIFIED BY '123'; and press Enter (don't forget to substitute the real username, host, and password in the query). MySQL displays, Query OK, 0 Rows Affected if the command was successful.
6. Use the GRANT command to give your user account (in this case, john_doe) permission to use the database you imported; type GRANT INSERT,DELETE,UPDATE,SELECT ON sample_journal.entries TO 'john_doe'@'localhost'; and press Enter (don't forget to substitute the real journal name, username, and host in the query). MySQL displays, Query OK, 0 Rows Affected if the command was successful.
   FYI: You should only grant permissions that are absolutely necessary (i.e. INSERT, DELETE, UPDATE, and SELECT) because additional permissions do not make your account work any better and can actually be dangerous to other databases.
7. Type exit and press Enter to disconnect from the MySQL command line.

MySQL requires you to use a GRANT query to give yourself permission to view and/or modify a remote journal database on your workstation. For instance, assume that a journal database called "test" is stored on 192.168.2.1 and you wish to access it through the "john_doe" user account on your workstation at 192.168.2.3. You would log in (as root) to the MySQL command interface on 192.168.2.1 and run GRANT INSERT,DELETE,UPDATE,SELECT ON test.entries TO 'john_doe'@'192.168.2.3'; to give yourself permission to access the journal. You are ready to begin the journal selection procedure once you have assigned the correct permissions to the database you wish to set as your default.

If you need to enable remote root logins, execute GRANT ALL PRIVILEGES ON *.* TO 'root'@'[host]' IDENTIFIED BY '[password]' WITH GRANT OPTION; where [host] refers to the host you wish to enable remote access from (for instance, 192.168.2.4) and [password] indicates the current root password. Using the wild card (%) value for [host] is extremely dangerous because it allows root access from any computer. After executing that query, run FLUSH PRIVILEGES; and quit the current MySQL session. Next, open the MySQL configuration file (my.cnf) in a text editor and comment out the line that says "bind-address = 127.0.0.1". Save the file and quit. Remote root access will be enabled the next time the MySQL server starts.

## Connecting to an Existing Journal Database

RoboJournal's journal selection tool provides an easy way to select the default journal during the first-run session or any other time the default journal needs to be changed. This tool allows you to specify the username and password for a pre-existing account on a host machine (local or remote). Once you have provided this information, RoboJournal displays all databases associated with that specific user account. If you do not have a user account at this time, you must use the Assign Permissions extension to create a new account and bind at least one journal database to it before you can use the Journal Selector.

In order to use the Journal Selector successfully, you must know the correct username and password for the account you wish to access since RoboJournal currently has no way of retrieving a full list of accounts from the host. Furthermore, this tool only lists databases that are associated with the user account you provide (all others are ignored). Before you use the Journal Selector, you must assign the correct user permissions to the database you wish to use or RoboJournal will be unable to find it.

Click to select the Connect to an existing journal database option on the Welcome to RoboJournal dialog and click the OK button. If RoboJournal is not in first-run mode, click the Journal Selector option on the main window's Database drop-down menu:

Figure 11: The Journal Selector is launched via the Welcome to RoboJournal dialog or the Database drop-down menu on the main window.In both instances, the Journal Selector window is displayed: Figure 12: The Journal Selector's default appearance.

The Journal Selector in RoboJournal 0.5 and later is designed to work with multiple database types. This functionality is controlled by the Type drop-down menu in the Backend group and affects which window options are available at any given time. The Journal Selector always starts in MySQL mode, which means it is configured to work with MySQL databases by default. As such, the Connection and User Settings group is unlocked and ready for input. The Browse button in the Backend group is always locked while the Journal Selector is in MySQL mode because file browsing functionality is inapplicable to MySQL databases. On the other hand, switching to SQLite mode causes the Connection and User Settings group to lock and the Browse button to unlock because SQLite databases exist as discrete files on your computer's hard drive.

### Selecting a MySQL Journal

1. Change the Host and Port values if necessary. Clearing their contents causes RoboJournal to use the default host and port settings specified in RoboJournal Preferences.Figure 13: The Host and Port fields are automatically populated with the most common default values.
2. Enter the appropriate username and password into their respective fields (indicated within the red circle in Figure 14). These values should belong to the account you wish to use as your own (do not use root). The contents of the Password field are always obscured for security reasons. Figure 14: Fill in the indicated fields to display a list of journals associated with a specific account.
3. Click the Search for Journals button.
4. A list of journals associated with the user account you provided is displayed in the large open area on the left:Figure 15: The Journal Selector displays all databases associated with a specific user account.
5. Select the journal you wish to use by clicking on its node in the hierarchy. Once a journal has been selected, the OK button on the Journal Selector window is unlocked (as shown in Figure 16).
6. Click the OK button to continue.Figure 16: The OK button unlocks once you have selected an entry.
   FYI: The next two steps are displayed only if RoboJournal is in first-run mode. Otherwise, RoboJournal preserves the user's full name and gender settings from the current configuration.
   If RoboJournal is not in first-run mode, you are asked to confirm your decision to replace your current default journal. Your previous settings are not changed at all if you decide to abort.
7. A text input dialog is displayed. Enter your name (as you prefer it) and click the OK button. You can click the Cancel button if you wish to skip this step.Figure 17: This value sets the user's full name in the configuration file.
8. A gender selection dialog is displayed. Select your gender by clicking the appropriate button.Figure 18: The gender selection dialog determines which avatar icon is used while a connection is active.

RoboJournal is now successfully configured. For more information on how to use core RoboJournal functionality, refer to the RoboJournal Fundamentals documentation.

Copyright © 2014 by Will Kraft. All parts of the RoboJournal Documentation are subject to the terms of the GNU Free Documentation License.

>>>>>>> experimental