Skip to main content

Contacting support

A report that includes the versions, the state of the cluster, the log from around the event, and the configuration in effect at that event can be answered from what the report holds. A report that includes only the symptom is answered with a request for the rest, one item at a time. This page covers what to collect, how to collect it, what to leave out, and where to send it.

Check the symptom pages before you write​

Start at the symptom you can see. That page sorts the common failures by what you observe rather than by what causes them. Check the FAQ as well, which answers the questions that are asked most often. Whatever you check there belongs in the report anyway, because a check that you ran and the result that it returned are part of what the report has to say.

Collect versions and cluster state in one call​

Every Master Server, Metalogger, Chunkserver, and mount that is connected reports its own version to mfscli. One call therefore answers the version question for the whole cluster and records the state of the cluster at that time:

mfscli -SIN -SCS -SHD -SMS -j > cluster-state.json

-j writes the output as a single JSON object. Attach that form, because the framed tables are replaced by a different format as soon as the output is not a terminal. What each section returns is described on the CLI page. That page also says which sections query the Chunkservers themselves, not only the Master Server.

A component that is not connected is missing from that output. That is the case whenever a mount does not start or a Chunkserver does not register. Read its version on the machine where it runs. Each server module prints it with -v, and the client with -V:

mfsmaster -v
mfschunkserver -v
mfsmetalogger -v
mfsmount -V

Name the operating system and the kernel version of every machine the report is about. On a Unix system uname -a prints both.

Cut the log to one module and window​

Each module reports to the system log of its own machine under its own identifier, so select an excerpt by identifier and by time. On a machine whose log is kept by journald:

journalctl -t mfsmaster --since "<YYYY-MM-DD HH:MM>" --until "<YYYY-MM-DD HH:MM>" > mfsmaster-log.txt

Open the window before the symptom rather than at it, and take the same window from every machine involved. Name the module that runs there: mfschunkserver, mfsmetalogger, mfsmount. A mount that failed is the exception. It reports to the terminal of the command that started it, not to the log. Copy that output while it is still on screen. A server module that failed to start writes to both at once. Its earliest messages, those about the configuration file, appear only on the terminal, so take the terminal output as well as the log excerpt.

Send the configuration as the process reads it​

The info action makes a module record its version, its build number, and the configuration as the process read it. That configuration includes overrides from the command line and the environment. It also records the counters of every module inside the process. The file is written to the data directory, hidden by its leading dot, as .mfsmaster_info.txt, .mfsmetalogger_info.txt, and .mfschunkserver_info.txt. Reading it is described with the other diagnostic tools.

mfsmaster info
mfschunkserver info
mfsmetalogger info

Run the action on every server module the report is about, on the machine that runs it. A module started with a configuration file of its own needs -c here as well. It writes its file into that instance's data directory (several processes on one machine).

When the case is about a rule rather than a reading, attach the file that holds the rule as well. That is mfsexports.cfg for a client that cannot mount what it should, and mfshdd.cfg for a disk that is not in service. Every file that a module reads is listed in the configuration files.

Keep credentials and file contents out​

Replace a secret with a placeholder instead of deleting the line that holds it, so that the report still shows that the option is set.

  • AUTH_CODE in mfsmaster.cfg, mfschunkserver.cfg, and mfsmetalogger.cfg. The info file repeats it, because the file prints the configuration as read.
  • password= and md5pass= entries in mfsexports.cfg, and the mount options mfspassword= and mfsmd5pass= wherever they are set, the file that mfspassfile= points to included.
  • The contents of stored files. The way a file is stored is a different question from what is written in it. mfsfileinfo answers the first question: it reports where the chunks of that file are and what state each of them is in.
  • Names, when the names themselves are confidential. The operations log of a mount and the changelog of the Master Server both record the name of every object they touch, so read an excerpt of either before you send it.

Describe the symptom, its reach, and what changed​

  • What you did, what happened, and what you expected instead.
  • When it started, in local time with the offset, and whether it is still going on.
  • Whether it repeats: every time, on one operation, or once so far.
  • How far it reaches: one process, one mount, one server, or every client at once.
  • What changed before it: an upgrade, a configuration change, hardware work, a network change.
  • What you checked already and what each check returned.

Quote messages, status words, and counts as they appear on screen rather than describing them.

The report is complete when it carries everything​

What to attach, section by section:

  1. The checks you ran: which of them you ran and what each one returned.
  2. The state of the cluster: the JSON from one mfscli call, the version read on the spot from anything that is not connected, and the operating system and kernel of every machine the report is about.
  3. The log: an excerpt per machine involved, selected by the module's identifier over a window that opens before the symptom. For a mount that failed, the terminal output instead. For a start that failed, the terminal output as well as the excerpt.
  4. The configuration as the process reads it: the info file from each server module involved, plus the file that holds the rule when the case is about a rule. A mount has no info file, so its configuration is sent as the mount options instead.
  5. The redactions: every credential, password entry, and confidential name replaced by a placeholder rather than deleted.
  6. The description: what happened, when it started, whether it repeats, how far it reaches, and what changed before it, quoted as it appears on screen.

An active subscription reaches the support team directly​

If you already have an active MooseFS support subscription, send the report to the support team at support@moosefs.com.

To buy a MooseFS support plan or a commercial license, write to the sales team at contact@moosefs.com. They answer questions about the available support tiers, licensing options, and pricing.

For material that is not a case of your own, the official MooseFS website has guides, FAQs, and best practices next to this documentation.