riak / doc / admin.org

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
#+TITLE: Riak Administration Guide
#+STYLE: <link rel="stylesheet" type="text/css" href="doc-style.css" />

* Overview

  This document is a guide for people who want to run Riak.  It
  discusses [[Downloading%20Riak][downloading]], [[Installation][installing]], [[Configuration][configuring]], and [[Running%20Riak][running]] Riak, as
  well as basic [[Client%20Interaction][client interaction]].

  As always, questions are welcome on the [[http://lists.basho.com/mailman/listinfo/riak-users_lists.basho.com][Riak mailing list]],
  riak-users@basho.com.  The latest version of this document, and
  other Riak information is available at [[http://riak.basho.com/]].


* Downloading Riak

  Riak can be downloaded as a pre-built, binary release for many
  popular platforms, or as source code, ready to build on most
  platforms supporting [[http://erlang.org/][Erlang]] releases R13B03 and later.

** Binary Releases
*** TODO where do binary releases come from?
*** TODO List of OS packages

** Source Releases
*** Prerequisites

    To build Riak from source, you will need Erlang/OTP version R13B03
    or later installed.  Erlang is available at [[http://erlang.org/]].

*** Obtaining Riak Source

    The source for tagged Riak releases is available as tarballs at
    [[http://hg.basho.com/riak/downloads/]].  Once downloaded, unpack the
    tarball in a convenient location.

    If you prefer to follow the latest Riak development, use Mercurial
    to clone the public repository:
    : hg clone http://hg.basho.com/riak

*** Building Riak from Source

    Building Riak should be as simple as running =make= in the top
    level of the source directory.

#+BEGIN_EXAMPLE
    $ make
    ./rebar compile
    ==> mochiweb (compile)
    Compiled src/mochifmt_std.erl
    Compiled src/mochifmt_records.erl
    Compiled src/mochifmt.erl
    Compiled src/mochihex.erl
    ...snipped...
    ==> webmachine (compile)
    Compiled src/webmachine_app.erl
    Compiled src/webmachine.erl
    Compiled src/webmachine_deps.erl
    Compiled src/webmachine_error_handler.erl
    ...snipped...
    ==> riak (compile)
    Compiled src/gen_server2.erl
    Compiled src/bloom.erl
    Compiled src/jaywalker_resource.erl
    Compiled src/jiak_client.erl
    ...snipped...
    Compiled src/slide.erl
    $
#+END_EXAMPLE

    (The =...snipped...= lines represent several lines of similar
    output, removed for display in this document.)

    If no errors are printed, Riak was built successfully.  See the
    [[Troubleshooting]] section of this document for help with build
    errors.

*** Creating the Release

    Riak's command line scripts expect the object files and their
    dependencies to be packaged into an Erlang release.  To create
    this release, simply run =make rel= in the top-level source
    directory.

#+BEGIN_EXAMPLE
    $ make rel
    ./rebar compile generate
    ==> mochiweb (compile)
    ==> webmachine (compile)
    ==> riak (compile)
    ==> rel (generate)
    Generating target specification...
    Constructing release...
    $
#+END_EXAMPLE

    That's it.  This process created an Erlang "embedded node" in
    rel/riak.  You should now be able to run Riak from that directory,
    or copy the directory to any other path on this machine, or to any
    other machine with matching architecture.  See the [[Installation]]
    section for more details.


* Installation
** Embedded Erlang Node

   If you downloaded a pre-built, binary release of Riak, or if
   you have made it through building the release from source, you
   should have an Erlang embedded node ready to run Riak in-place.
   No further installation is needed.

   To run Riak on other machines, simply copy the entire embedded
   node directory to those machines.  See the [[Configuration]] section
   for details about altering configurations for each machine.

** Installing to OTP Libary Path

   You also have the option of installing Riak into the Erlang/OTP
   library path.  This will make Riak modules available to all other
   Erlang applications on your system without needing to muck about
   with code paths.

   To install, simply execute =rebar install= in the top-level Riak
   directory.

#+BEGIN_EXAMPLE
    $ sudo ./rebar install
    ==> mochiweb (install)
    Installing: mochiweb-0.01
    ==> webmachine (install)
    Installing: webmachine-1.5
    ==> riak (install)
    Installing: riak-0.8
    $ ls $ERLANG_ROOT/lib/riak-*
    ebin	priv	src
#+END_EXAMPLE


* Configuration
** TODO Capacity Planning
** TODO OS Configuration  (noatime, separate disks, max fds, ...)
** vm.args

   Parameters for the Erlang node on which Riak runs are set in the
   =vm.args= file in the =etc= directory of the embedded Erlang node.
   Most of these settings can be left at their defaults until you are
   ready to tune performance.

   Two settings you may be interested in right away, though, are
   =-name= and =-setcookie=.  These control the Erlang node names
   (possibly host-specific), and Erlang inter-node communication
   access (cluster-specific), respectively.

   The format of the file is fairly loose: all lines that do not begin
   with the =#= character are concatentated, and passed to the =erl=
   on the command line, as is.

   More details about each of these settings can be found in the
   Erlang [[http://www.erlang.org/doc/man/erl.html][documentation for the =erl= Erlang emulator]].

*** Erlang Runtime Configuration Options

    + -name :: the name of the Erlang node (default: =riak@127.0.0.1=)

               The default value, =riak@127.0.0.1= will work for
               running Riak locally, but for distributed (multi-node)
               use, the value after the =@= should be changed to the
               IP address of the machine on which the node is running.

               If you have properly-configured DNS, the short-form of
               this name can be used (for example: =riak=).  The name
               of the node will then be =riak@Host.Domain=.

    + -setcookie :: the cookie of the Erlang node (default: =riak=)

                    Erlang nodes grant or deny access based on the
                    sharing of a previously-shared cookie.  You should
                    use the same cookie for every node in your Riak
                    cluster, but it should be a not-easily-guessed
                    string unique to your deployment, to prevent
                    non-authorized access.

    + -heart :: enable =heart= node monitoring (default: /disabled/)

                Heart will restart nodes automatically, should they
                crash.  However, heart is so good at restarting nodes
                that it can be difficult to prevent it from doing so.
                Enable heart once you are sure that you wish to have
                the node restarted automatically on failure.

    + +K :: enable kernel polling (default: true)

    + +A :: number of threads in the async thread pool (default: 5)

    + -env :: set host environment variables for Erlang

** app.config

   Riak and the Erlang applications it depends on are configured by
   settings in the =app.config= file in the =etc= directory of the
   embedded Erlang node.  The format of the file is similar to
   Erlang's ".app" files:

#+BEGIN_SRC erlang
   [
    {riak, [
            {storage_backend, riak_dets_backend},
            {riak_dets_backend_root, "data/dets"}

            %% More Riak settings...
           ]}
    %% Other application configurations...
   ].
#+END_SRC

   That is, the file starts with =[=, and ends with =].=.  Inside the
   square brackets are comma-separated application sections of the
   form ={ApplictionName, [Setting1, Setting2, ...]}=.  Each setting
   is a 2-tuple of the form ={SettingName, SettingValue}=.

*** List of Riak Configuration Variables

#+COMMENT TODO figure out verbatim escaping: ="blah"=

    + =ring_state_dir= :: the directory on-disk in which to store the
         ring state (default: ="data/dets"=)

         Riak's ring state is stored on-disk by each node, such that
         each node may be restarted at any time (purposely, or via
         automatic failover) and know what its place in the cluster
         was before it terminated, without needing immediate access to
         the rest of the cluster.

    + =ring_creation_size= :: the number of partitions to divide the
         hash space into (default: 64)

         By default, each Riak node will own
         (=ring_creation_size=)/(number of nodes in the cluster)
         partitions.  It is generally a good idea to specify a
         =ring_creation_size= a few times the number of nodes in your
         cluster (e.g. specify 64-256 partitions for a 4-node
         cluster).  This gives you room to expand the number of nodes
         in the cluster, without worrying about underuse due to owning
         too few partitions.

    + =riak_web_ip= :: the ip address on which Riak's HTTP interface
                       should listen (default: ="127.0.0.1"=)

                       Riak's HTTP interface will not be started if
                       this setting is not defined.

    + =riak_web_port= :: the port on which Riak's HTTP interface should
         listen (default: =8098=)

         Riak's HTTP interface will not be started if
         this setting is not defined.

    + =jiak_name= :: the base of the path in the URL exposing Riak's
                     JSON-based HTTP interface (default: ="jiak"=)

                     The default value will expose objects at
                     =/jiak/Bucket/Key=.  For example, changing this
                     setting to ="foo"= would expose the interface at
                     =/foo/Bucket/Key=.

    + =raw_name= :: the base of the path in the URL exposing Riak's
                    "raw" HTTP interface (default: ="raw"=)

                    The default value will expose data at
                    =/raw/Bucket/Key=.  For example, changing this
                    setting to ="bar"= would expose the interface at
                    =/bar/Bucket/Key=.

    + =storage_backend= :: module name of the storage backend that
         Riak should use (default: =riak_dets_backend=)

         The storage format Riak uses is configurable.  Riak will
         refuse to start if no storage backend is specified.

         Available backends, and their additional configuration
         options are:

         - =riak_dets_backend= :: data is stored in DETS files

              * =riak_dets_backend_root= :: root directory where DETS
                   files are stored (default: "data/dets")

         - =riak_ets_backend= :: data is stored in ETS tables
              (in-memory)

         - =riak_gb_trees_backend= :: data is stored in ETS tables
              (in-memory)

         - =riak_fs_backend= :: data is stored in binary files on the
              filesystem

              * =riak_fs_backend_root= :: root directory where files
                   are stored

         - =riak_multi_backend= :: enables storing data for different
              buckets in different backends

              Specify the backend to use for a bucket with
              =riak_bucket:set_bucket(BucketName, [{backend, BackendName}])=

              * =multi_backend_default= :: default backend to use if
                   none is specified for a bucket (one of the
                   =BackendName= atoms specified in the
                   =multi_backend= setting)

              * =multi_backend= :: list of backends to provide

                   Format of each backend specification is
                   ={BackendName, BackendModule, BackendConfig}=,
                   where =BackendName= is any atom, =BackendModule= is
                   the name of the Erlang module implementing the
                   backend (the same values you would provide as
                   =storage_backend= settings), and =BackendConfig= is
                   a parameter that will be passed to the =start/2=
                   function of the backend module.

         - =riak_cache_backend= :: a backend that behaves as an
              LRU-with-timed-expiry cache

              * =riak_cache_backend_memory= :: maximum amount of
                   memory to allocate, in megabytes (default: 100)

              * =riak_cache_backend_ttl= :: amount by which to extend
                   an object's expiry lease on each access, in seconds
                   (default: 600)

              * =riak_cache_backend_max_ttl= :: maximum allowed lease
                   time (default: 3600)

    + =add_paths= :: a list of paths to add to the Erlang code path

                     This setting is especially useful for allowing
                     Riak to use external modules during map/reduce
                     queries.

    + =default_bucket_props= :: properties to give each bucket, by
         default

         Properties in this list will override the hardcoded defaults
         in riak_bucket:defaults/0.  This setting is the best way to
         set things like:

         - the default N-value for Riak objects (=n_val=)
         - whether or not siblings are allowed (=allow_mult=)
         - the function for extracting links from objects (=linkfun=)

    + =riak_stat= ::
      enable the statistics-aggregator (default: false)

    + =riak_handoff_port= :: 
         TCP port number for the handoff listener (default: 8099)
                     
    + =handoff_concurrency= :: 
         Number of vnode, per physical node, allowed to perform handoff at once.





    + =js_vm_count= :: how many Javascript virtual machines to start (default: 8)

    + =js_source_dir= :: where to load user-defined built in Javascript functions (default: unset)

** Rebar Overlays

   If you are going to be rebuilding Riak often, you will want to edit
   the =vm.args= and =app.config= files in the =rel/overlays/etc=
   directory.  The copies of those files in the release (embedded
   node) directory will be overwritten by the files in the =overlays=
   directory when a =make rel= or =rebar generate= command is issued.


* Running Riak

  Riak is controlled using the =riak= and =riak-admin= scripts in the
  =bin= directory of the release.

** The =riak= script

   This script is the primary interface for starting and stopping the
   Riak server.  It takes one parameter, the command to execute:

   : $ bin/riak COMMAND

   Available commands are:

   + console :: start a Riak node in the foreground, which the
                console/Erlang shell attached

   + start :: start a Riak node in the background (daemonized)

              Running =start= will print an warning if the Riak node
              is already running.

   + attach :: attach a console to a daemonized Riak node

   + ping :: check whether or not the Riak node is alive

             The script should print out =pong= if it finds a live
             Riak node, or an error about not responding to pings if
             it does not.

   + stop :: stop a running Riak node

             If you have a shell connected to the node, you can also
             use the =q()= command.

             : (riak@example.com)1> q().

** The =riak-admin= script

   This script provides access to general administration of the Riak
   server.  The Riak node should be running before using the
   riak-admin script.

   Much like the =riak= script, =riak-admin= expects a command, plus
   options on the command line.

   : $ bin/riak-admin COMMAND [OPTIONS]

   Available commands are:

   + test :: writes and reads a Riak object, to test basic
             functionality

             The code for the test is in =riak:client_test/1=, if you
             would like to evaluate it.

   + join :: join a running Riak cluster

             This command requires one option: the node in the running
             cluster to which to connect.  Example:

             : $ bin/riak-admin join riak2@example.com

   + backup :: backup the data in the cluster to a file

               This command requires three options: the node in the
               running cluster to which to connect , the Erlang cookie
               for that node, and the filename to store the backup
               under.  Example:

               : $ bin/riak-admin backup riak2@example.com riak backup.dets

   + restore :: restore data into a cluster from a backup file

                This command expects the same parameters as =backup=.

   + logger :: attach the riak event logger to the cluster

               This command requires at least two options: the node in
               the running cluster to which to connect, and the Erlang
               cookie for that node.  With just these two parameters,
               the log will print on the console.  Adding a filename
               as a third parameter will cause the log to be written
               to that file.

   + js_reload :: reload all Javascript virtual machines

               This command will reload the Javascript virtual machines on the node
               where the command is executed.

               : $ bin/riak-admin js_reload

** Simple startup

   To start a Riak node, simply install riak (by either copying the
   rel/riak directory from an existing build, or compiling with =make
   rel= on the new machine), and then run =bin/riak start=.

   The node will start in the background.  To attach to the running
   node's Erlang console, run =bin/riak attach=.  Use Control-D to
   exit the console, but leave the node running.

** Cluster startup

   A single node is its own cluster.  To add new nodes to a cluster,
   first start a new node, just as you would for solitary operation:
   =bin/riak start=.

   Once the new node is up, ask it to connect to the existing cluster
   by running =bin/riak-admin join NODE@HOST=, where =NODE@HOST= is
   the name of a node in the existing cluster (from the =-name=
   argument in vm.args).  You should see a message of the form "Sent
   join request to NODE@HOST" (see [[Startup Errors]] if you don't).

   After the node has joined the cluster, you can verify that it has
   claimed partitions by attaching to a console in the cluster and
   requesting a copy of the claim ring:

: 1> {ok, R} = riak_ring_manager:get_my_ring().
: {ok,{chstate,...
: 2> riak_ring:all_members(R).
: ['riak@10.0.0.1','riak@10.0.0.2','riak@10.0.0.3']

   You should see the names of all the nodes in your cluster in the
   list returned from that command.

   Re-starting a node, after it has been shut down is even easier.  As
   long as you haven't removed the on-disk ringfile, you should only
   need to run =bin/riak start=.  The startup will read the ringfile,
   and automatically connect to the cluster it was part of when it
   shut down.

** Verifying your Installation

   A simple way to verify a running Riak installation is with
   =bin/riak-admin test=:

: $ bin/riak-admin test
:
: =INFO REPORT==== 25-Jan-2010::14:09:08 ===
: Successfully completed 1 read/write cycle to 'riak@127.0.0.1'

   The script attempts to write a value, and then read it back.  If
   all goes well, you should see output similar to the example above.
   See [[Client Errors]] for help with error messages from this script.

** Shutting down a node

   Stopping a Riak node can be done at any time, simply by running
   =bin/riak stop=:

: $ dev/dev3/bin/riak stop
: ok

   This halts the Riak node, but it does not change any claims on the
   ring.  That is, the rest of the cluster still believes that the
   node that just shut down is still responsible for storing some
   slice of the cluster's data.

   To change ring ownership, such that a node is no longer responsible
   for storing any data, first get a riak client, then use
   =remove_from_cluster/1= to move that node's claims to other nodes:

: $ bin/riak attach
: Attaching to ... (^D to exit)
:
: (riak@10.0.0.1)1> {ok, C} = riak:local_client().
: {ok,{riak_client,'riak@10.0.0.1',<<0,166,141,137>>}}
: (riak@10.0.0.1)2> C:remove_from_cluster('riak@10.0.0.3').
: [ok,ok,ok,ok|...]

   If the node that is leaving is alive and connected to the cluster,
   it will start transfering data to the nodes that have claimed the
   partitions it just owned.  If the node is down, no data transfer
   happens.

   Read and write requests immediately start hitting the nodes that
   have claimed the partitions that the exiting node just gave up.
   This means that some reads where R=N will fail for a time, until
   data exists everywhere.  Data will exist everywhere it is supposed
   to after handoff finishes, after a successful read repair, or after
   a write to all partitions responsible for a value.

* Client Interaction
** TODO Client Libraries
** TODO HTTP Interface
** TODO Using an HTTP Cache


* Troubleshooting

** Build Errors

*** Rebar requires at least erts 5.7.4; ...

    Riak supports only Erlang/OTP version R13B03 and later.  To check
    your installed OTP version:

#+BEGIN_EXAMPLE
    $ erl
    Erlang...

    Eshell Vx.x.x (abort with ^G)
    1> erlang:system_info(otp_release).
    "R13B03"
#+END_EXAMPLE

    If the version printed is earlier than R13B03 (for example R13B02,
    or R12B), you will need to upgrade your Erlang installation before
    being able to build Riak from source.

*** ERROR: Release target directory "XXX" already exists!

    If you have previously generated a release, or installed a release
    to the OTP library path, you will receive this error if you
    attempt to generate a new release of the same version.  Possible
    resolutions are:

    + =make relclean= to clean out the =rel= directory

    + =rm -rf $ERLANG_ROOT/lib/XXX=

    + change the application version in the =.app= and
      =rel/reltool.config= files

** Startup Errors

*** Node is not running! / Node 'XXX' not responding to pings.

    If the =bin/riak= or =bin/riak= refuse to connect to a node, one
    of several things may be going awry:

    - The node may not be running.  Use =ps= to check for running
      instances of =beam=, the Erlang virtual machine.  The arguments
      to that VM should include paths to your Riak installation.

    - If =etc/vm.args= is using the short-form of Erlang node names
      (without =...@IP-OR-HOSTNAME=), then DNS on the machine may be
      configured incorrectly.  The easiest fix is to explicitly set
      the hostname using the long form =-name NODE@IP-OR-HOSTNAME= in
      =etc/vm.args=.

    - Erlang distribution cookies may not match.  If you started the
      Riak node with =bin/riak console=, or you are able to open a
      console with =bin/riak attach=, check the node's cookie with
      =erlang:get_cookie/0=:

: (riak@127.0.0.1)1> erlang:get_cookie().
: riak

      That cookie should match the cookie in =etc/vm.args=.  The
      =bin/riak= and =bin/riak-admin= scripts should be using the same
      cookie.

      The startup or admin scripts may be tricked into using different
      cookies by specifying an =ERL_FLAGS= environment variable.  If
      you have specified such a variable in your shell, unset it, and
      move those settings to =etc/vm.args=.

*** TODO riak-admin join errors


** TODO Client Errors
*** TODO riak-admin test errors

* TODO FAQ
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.