FCPv2 ClientPut

Description

ClientPut is used to specify an insert into Freenet of a single file. This may be provided by referring to a file on disk, including the data directly in the message, or redirecting to another key.

A filename may be specified using the TargetFilename option. This is mostly useful with CHKs. The effect is to create a single file manifest which contains only the filename given, and points to the data just inserted. Thus the provided filename becomes the last part of the URI, and must be provided when fetching the data. See Single-file manifest for details.

Example

 ClientPut
 URI=CHK@
 Metadata.ContentType=text/html
 Identifier=My Test Insert
 Verbosity=0
 MaxRetries=10
 PriorityClass=1
 GetCHKOnly=false
 Global=false
 DontCompress=false
 Codecs=LZMA
 ClientToken=Hello!!!
 UploadFrom=disk
 Filename=/home/toad/something.html
 TargetFilename=me.html
 FileHash=Base64String
 BinaryBlob=false
 CompatibilityMode=COMPAT_CURRENT
 LocalRequestOnly=false
 EndMessage

Field	Possible values	Mandatory	Default	Condition	Description
URI	CHK@ KSK@name SSK@privateKey/docname-1 USK@privateKey/docname/0/	yes			The type of key to insert. When inserting an SSK key, you explicitly specifiy the version number. For a USK key, use a zero and it should automatically use the correct version number.
Metadata.ContentType	Any MIME type	no	application/octet-stream		The MIME type of the data being inserted. For text, if charset is not specified, node should auto-detect it and force the auto-detected version
Identifier	Arbitrary text string	yes			This is just for client to be able to identify files that have been inserted.
Verbosity	Bitmask	no	0		Allows additional insertion status updates beyond the standard FCPv2-PutSuccessful and FCPv2-PutFailed updates. bit 0: send FCPv2-SimpleProgress messages bit 3: send FCPv2-ExpectedHashes message bit 8: send FCPv2-PutFetchable message bit 9: send FCPv2-StartedCompression and FCPv2-FinishedCompression messages
MaxRetries	Integer -1 to 999999+?	no	0		Number of times to retry if the first time doesn't work. -1 means retry forever.
PriorityClass	[0..2..6]	no	2 (Semi-interactive priority class)		How to prioritize the insert.
GetCHKOnly	[true,false]	no	false		If set to true, it won't actually insert the data, just return the key it would generate. If the key is USK, you may want to transform it into a SSK to prevent the node spending time searching for an unused index.
Global	[true,false]	no	false		Whether the insert is visible on the global queue or not. If you set this as true, you should probably do a WatchGlobal, or you won't get any FCPv2-PutSuccessful / FCPv2-PutFailed message
DontCompress	[true,false]	no	false		Hint to node: don't try to compress the data, it's already compressed
Codecs	a comma separated list of either names or ids	no			The node will try to compress the data with the given codec(s). If more then one codec is given the node will try to find the best in the given order. The node tells the supported codecs in the NodeHello message. This setting was introduced in 1231.
ClientToken	Arbitrary string	no			Returned to the client in the PersistentPut message if this is a persistent request.
Persistence	[connection,reboot,forever]	no	connection		Whether the insert stays on the queue across new client connections, Freenet restarts, or forever
TargetFilename	A filename (no slashes)	no	Extracted from URI or Filename		Filename to be appended to a CHK insert. Technically it creates a one-file manifest with this filename pointing to the file being uploaded. Ignored for all types other than CHK since other types have human-readable filenames anyway. Empty means no filename.
EarlyEncode	[true,false]	no	false		See EarlyEncode
UploadFrom	[direct,disk,redirect]	no	direct		Whether the FCP message includes the actual data, just the disk filename and path, or a redirection to an existing freenet key. If you upload from disk, you have to do a TestDDARequest.
DataLength	Integer from 0 to ?	yes		UploadFrom is direct	The length of the data file being included in this FCP message
Filename	The full path of a file	yes		UploadFrom is disk	The full name and path of the file you wish to insert to Freenet
TargetURI	A freenet URI	yes		UploadFrom is redirect	This is an existing freenet URI such as KSK@sample.txt. The idea is that you insert a new key that redirects to this one.
FileHash	Base64 encoded SHA256 hash	no			Base64 encoded SHA256 hash of the content you want the node to insert. This is only useful if you use UploadFrom=disk. This field will allow you to override any TestDDA restriction if you provide a hash of the content which should be inserted. It should be computed like this : Base64Encode(SHA256( NodeHello.identifier + '-' + Identifier + '-' + content)). This setting was introduced in 1027.
BinaryBlob	[true,false]	no	false		If true, insert a binary blob (a collection of keys used in the downloading of a specific key or site). Implies no metadata, no URI.
ForkOnCacheable	[true,false]	Depends on node version	true		Override insert behaviour: If true, fork an insert after its HTL becomes low enough for it to be cacheable. If false, don't fork the insert at this point. Inserts are not cached while their HTL is above 15, after that they can be cached, but this can be many hops because of probabilistic decrement, hence they may go over the "ideal" nodes or "sinks" where they should have been cached while they are still not allowed to, and the insert will not go back to those nodes because it's already been there. Forking deals with this by creating a new insert, which can go back over nodes we've already been to if necessary.
ExtraInsertsSingleBlock	Integer >= 0	no	2 (from 1297)		Insert single blocks (not blocks above splitfiles, and not blocks in splitfiles) additional times. Testing has shown that a value of 2 (3 inserts total) can dramatically improve data persistence. We are still trying to figure out why.
ExtraInsertsSplitfileHeaderBlock	Integer >=0	no	2		Insert blocks above splitfiles additional times. E.g. the CHK at the top of a splitfile, the CHK you actually fetch, is a single block. The splitfile itself has redundancy but the top block doesn't. So we insert it multiple times (3 by default) to improve the number of nodes it gets stored on. Tests show this dramatically improves data persistence, we are still trying to figure out why.
CompatibilityMode	[COMPAT_CURRENT,]	no	COMPAT_CURRENT		Insert the data in a way that is identical to how older nodes inserted it, not taking advantage of improvements in the metadata format, so that we can generate the same CHK and do reinserts, so that the old keys still work. COMPAT_1250 actually uses the 1251 version of even segment splitting, but doesn't add an extra block to smaller segments (so doesn't cause pre-1250 nodes to crash); COMPAT_1250_EXACT inserts segments of exactly 128 blocks except for the last one, so inserts exactly the same as older nodes. 1251 introduces even segment splitting (with extra blocks for sub-128 block segments), 1254 introduces better even segment splitting and a variety of other changes e.g. hashes, single splitfile key. It is likely that 1255 will include further metadata changes for large files.
LocalRequestOnly	[true,false]	no	False		If true, data will be inserted into the datastore, not sent to the network. Only useful for testing, as nobody will be able to find the data; also unsafe in that it inserts local content directly to your store.
OverrideSplitfileCryptoKey	256 bit key in hex	no			If set, the bottom layer of any splitfiles inserted will be encrypted using this key, rather than a key derived from the hash of the content. This is useful for reinserting data that was inserted to an SSK. SSKs automatically use a random key for the bottom layer splitfile as of 1254, unless CompatibilityMode is set to an earlier version. Note that upper layers (i.e. multi-level metadata) are still encrypted according to the data hash; they are not predictable so there is no need to complicate matters.
RealTimeFlag		no	false		Whether to fetch the data with the real-time flag set to realtime (true) or bulk (false). (since 1311)
MetadataThreshold	Number of bytes (long)	no	-1		If >0, Freenet will try to return metadata smaller than the size given rather than a URI. This allows on-Freenet structures to have redundancy all the way up the pyramid, for instance Library's b-tree indexes. Instead of having a single CHK at the top, you have a small block of metadata which is included in the key referring to this key - which is a redundant splitfile, improving reliability. (From 1380)
EndMessage				UploadFrom is not direct	Indicates the end of the message. No data follows this line.
Data				UploadFrom is direct	Indicates the end of the message. The data follows this line. (Immediately after the newline).