package Ubic::Manual::FAQ;
# ABSTRACT: frequently asked questions about Ubic


__END__
=pod

=head1 NAME

Ubic::Manual::FAQ - frequently asked questions about Ubic

=head1 VERSION

version 1.35_01

=head1 QUESTIONS

=head2 I changed my service's user, and now it fails with "Permission denied" error. Please help!

You have to chown your service files manually. Try this:

    find /var/lib/ubic -name '*MY_SERVICE_NAME*' | xargs chown -R MY_NEW_USER

In the future, this one-liner will be reimplemented as "ubic fix-permissions" command. Sorry for the inconvenience.

=head2 I'm trying to add service with the dot in its name, but it doesn't show in C<ubic status> list, what's wrong?

Dot is a reserved symbol, it separates service name parts in service tree (like C</> separates directories in unix filesystems). So, if you really want the service C<foo.bar>, put its description in C</etc/ubic/service/foo/bar>.

By the way, this behavior is consistent with many classic unix programs, such as cron and logrotate.

=head2 Why did ubic edit my crontab?

Ubic uses cron as the way to bootstrap all its services. This crontab entry will bring the C<ubic.watchdog> up if it ever goes down, and it will then start all other services as necessary.

Even though watchdog itself is very robust, this mechanism is also useful on host reboots.

If you B<really> don't like it, you can pass C<--no-crontab> option to C<ubic-admin setup> command while configuring ubic instance (or just answer C<no> to the appropriate question).

=head2 What is this ubic-guardian process I see in my "ps aux" output?

This process guards any daemon started with C<Ubic::Daemon> module.

Optionally, ubic-guardian can write some information to its log, for example, the exit code or signal in case of service failure. Despite its name, ubic-guardian *does not* restart the service on failures. It's the job for the completely different program, ubic-watchdog.

It also holds the lock on pidfile for a whole lifetime, which theoretically makes daemons more secure, but it's more of a historical nuance than the necessity.

It's probable that ubic-guardian will become optional in the future (i.e. it will only be created if service asks for ubic_log).
Anyway, don't worry about it, it's completely harmless.

=head2 What does ubic.update service do?

C<ubic.update> service (and ubic-update script) updates portmap - local C<{ port => service-name }> mapping.
It makes possible to check a service status via C<ubic.ping> using service port instead of its name:

    $ wget -q -O - 'http://localhost:12345/status/port/12345'
    ok

Resolving of service by port can't be done on-the-fly by C<ubic.ping>, because all service definitions are cached internally by Ubic.pm (L<Ubic::Multiservice>, actually, but you don't have to know the difference), since constant reloading of service definition can cause memory leaks.
So C<ubic.ping> just loads portmap generated by C<ubic.update> instead, resolves service name by port, and loads cached service status from another local file.

In other words, if you don't use C<ubic.ping>, you can stop both C<ubic.update> and C<ubic.ping> services.

=head2 How is ubic compatible with SysV-style /etc/rcX.d/ symlinks?

No, it is not. It's recommended that you don't use C<chkconfig> or C<update-rc.d> or similar tools for installing runlevel symlinks at all.

In ubic, desired service status is stored at JSON files at I</var/lib/ubic/status/> dir. There is no support for runlevels. After reboot, C<ubic.watchdog> will simply start all your services which were started earlier.

This can be fixed in the future by adding abstraction layer to status storage. If you really need runlevels (or chkconfig compatibility), feel free ask again (or implement this abstraction layer yourself).

=head2 Why is it called "ubic", anyway?

It's called after "Ubik" - science fiction novel by Philip K. Dick. I spelled it incorrectly in early releases, because "c" and "k" are indistinguishable in Russian language, and now it's too late to fix this stupid typo (and I'll be very thankful to anyone who'll invent appropriate backronym).

Why is it called after "Ubik"? Well, these two quotes can hint to some suggestions:

  "This substance, whose name is derived from the word "ubiquity", has the property of preserving people who are in half-life."
  "Ubik is a metaphor for God. Ubik is all-powerful and all-knowing, and Ubik is everywhere."

=head1 AUTHOR

Vyacheslav Matyukhin <mmcleric@yandex-team.ru>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Yandex LLC.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut

